在 Celigo 集成中编写字段映射与转换时…

适用于在 Celigo 集成中编辑 imports 的 mappings[]、exports 的 transform{}、responseMapping 或 lookup 配置时，安全地重塑源系统与目标系统之间的数据。

适用场景

解决思路

1. 判断数据重塑方向：向目标系统输出的数据用 mappings；从来源进入管道的数据用 transformations；不要用上游 transformation 匹配目标形状，目标形状由目标 import 的 mapping 处理。
2. 只在两种情况下使用 upstream transformation：多个来源汇入一个管道时，把每个新来源重塑为现有步骤期望的规范记录形状；源数据确实混乱时，在入口一次性展平深层嵌套。单一且形状良好的源不要添加 transform，并跳过不重命名的 identity transforms。
3. 按上下文选择映射系统：HTTP、RDBMS、FTP、S3 等 import 字段映射用 Mapper 2.0 的 mappings[]；NetSuite/Salesforce import 用 Mapper 1.0 的 mapping.fields[]；export 数据重塑用 Transformation 2.0 的 transform{}；lookup/import 回写用 Transformation 1.0 的 extract/generate pairs；值翻译用 lookups[]。
4. 编辑现有 import 时，先检查是 Mapper 2.0 的 mappings[] 还是 Mapper 1.0 的 mapping.fields[]；绝不要混用；许多旧 HTTP/RDBMS import 也可能用 Mapper 1.0。
5. Mapper 2.0 工作流第一步：用 celigo imports get <importId> 和 celigo account search <keyword> 获取并检查现有资源状态及映射格式。
6. 理解源数据形状：用 celigo exports invoke <exportId> 查看真实记录，或用 celigo metadata fields <sourceConnectionId> <entityType> 查询源系统完整字段列表。
7. 理解目标数据形状：用 celigo metadata types <targetConnectionId> 列出实体类型，用 celigo metadata fields <targetConnectionId> <entityType> 查询目标系统必填字段和类型。
8. 选择 input context：在 mapper UI 的 Input context 下拉中设置 record（默认，extract 路径如 $.user_id 直接引用记录字段）或 envelope（extract 路径如 $.record.user_id，并可访问 $.settings.connection.api_username、$.job.type、$.settings.flow.fieldName 等元数据）。
9. 当 API/tool 需要在 mapping 中直接使用请求上下文 headers、path params、query params、connection settings 时使用 envelope；在 API/tool step 开头的 transform 上也使用 envelope；envelope 可用 $.settings.connection.fieldName 替代 {{settings.connection.fieldName}} Handlebars。
10. 每个 Mapper 2.0 mapping 必须配置 generate 目标字段名、dataType 输出类型、extract 获取数据方式。
11. Extract 三种写法：JSON path 以 $. 开头，始终引用顶层 root，即使嵌套 mapping 也如此；Handlebars 包含 {{，用于计算值；硬编码为纯字符串字面量，既无 $. 前缀也无 {{。
12. 简单类型 string、number、boolean、date 直接字段到字段映射；date 映射设置 extractDateFormat/generateDateFormat 做转换。
13. 对象映射设置 dataType: object，在 mappings[] 数组添加子 mappings；generate 绝不能使用点号。
14. 数组映射设置 dataType 为 stringarray、numberarray、booleanarray、objectarray、arrayarray，并配置 buildArrayHelper[]。
15. 对象数组可用三种模式：仅 extract 拉取已有对象，如 extract: $.items[*]；仅 mappings 从单个字段构造对象，每个 buildArrayHelper 条目创建一个数组元素；extract + mappings 迭代源数组并重塑每个元素。
16. 使用 extract + mappings 时应用 composite object mechanism：extract 路径中的数组方括号 [*] 在 mappings 内塌缩为单对象，如 $.orders[*].items[*] 在子 extract 路径中变为 $.orders.items.fieldName，父上下文仍可访问如 $.orders.id、$.customerName。
17. 添加 lookups：在 mappings 旁定义 lookup，并通过 mapping 上的 lookupName 引用。
18. 静态 lookup 用 map 对象键值对，适合小且固定的集合，如国家代码、状态值。
19. 动态 lookup 用 _lookupCacheId 引用 LookupCache 资源，并可用可选 extract JSON path 从缓存对象拉取特定字段。
20. 为 lookup 设置 allowFailures: true 加 default，当 lookup key 缺失时继续处理。
21. 添加 conditionals 控制 mapping 何时生效：record_created 仅插入时、record_updated 仅更新时、extract_not_empty 当源为 null/空时跳过。
22. Transformation 2.0 工作流第一步：用 celigo exports get <exportId> 和 celigo account search <keyword> 检查现有 export 的 transform 配置。
23. 选择 Transformation 2.0 模式：create 构建全新记录，仅 mapped 字段出现在输出；modify 编辑现有记录上的特定字段，未映射字段透传；按需要干净新结构还是局部调整选择。
24. 在 Transformation 2.0 中写 mappings 时使用同一套 Mapper 2.0 语法：generate、dataType、extract、嵌套 mappings、buildArrayHelper、lookups，并同样支持 input context。
25. 在 API/tool 的 transform 上优先考虑把 input context 设为 envelope，以通过 JSON path 直接访问完整请求上下文 headers、path params、query params、connection settings，避免 Handlebars。
26. 配置 transform envelope：设置 transform.type: expression、expression.version: 2，把 mappings[] 和 lookups[] 放在 expression.rulesTwoDotZero 下，并设置所选 mode。
27. expression rules 不足时使用脚本替代：设置 transform.type: script，配置 script._scriptId 和 script.function 做程序化 transform。
28. 处理 NetSuite/Salesforce import 的 Mapper 1.0 时，使用扁平 mapping 对象下的两个数组：mapping.fields[] 是 body-level 字段映射，每项有 extract 或 hardCodedValue、generate 目标字段 ID，以及可选 lookupName、dataType、internalId、immutable、discardIfEmpty、conditional。
29. Mapper 1.0 的 mapping.lists[] 是 sublist/line-item 映射，每项有 generate（sublist ID，如 item）、jsonPath（源数组路径）、fields[]（列映射，属性同 body 字段并加 isKey 用于匹配现有行）。
30. NetSuite lookups 与静态 map 不同：查询实时 NetSuite 记录，使用 recordType、searchField、resultField、operator，定义在 netsuite_da.lookups[]，通过字段映射中的 lookupName 引用；用 celigo metadata fields <connectionId> <recordType> 发现 searchField/resultField 的有效字段 ID。
31. Salesforce lookups 遵循相同 Mapper 1.0 模式，但 lookup 结构更简单。
32. 发现 sublist 字段：NetSuite mapping.lists[].generate 的 sublist 名，如 item、addressbook，来自 celigo metadata fields <connectionId> <recordType>，sublists 会作为字段组出现；Salesforce related lists 用 celigo metadata fields <connectionId> <sObjectType> 发现关系字段和子对象名，用于 distributed.relatedLists[].sObjectType。
33. 规划 response mapping：它从 lookup 或 import API response 提取字段回原记录，位于 flow 的 pageProcessors[] 条目，不在 import 资源本身，但在构建资源时规划。
34. response mapping 的两个 section 都写成普通数组：fields[] 是字段级 extract/generate 对，用点号；lists[] 是数组映射，含 generate 目标数组名和 fields[]，对每个数组项应用 extract/generate 对；绝不要包成 fields: {type: [...]} 这类对象，API 接受该形状但会静默擦除步骤 mappings。
35. 对 lookup exports，response envelope 是 {statusCode: 200, data: [...result records], errors: []}，每个 extract 从 data 开始。
36. lookup 单结果时用 data[0].fieldName 或 data.0.fieldName。
37. lookup 多结果且保留整个数组时，用 extract: data、generate: <arrayField>；记录获得结果对象数组，下游步骤可用正常 JSON 数组路径，如 Mapper 2.0 中 $.<arrayField>[*].fieldName，或用 one-to-many 展开 pathToMany: <arrayField>。
38. lookup 多结果且要重塑时，添加 lists 条目，其字段 extracts 用 data[*].fieldName，每个结果生成一个数组项，[*] 标记要迭代的数组；例如 fields: [], lists: [{ generate: matchedOrders, fields: [{ extract: data[*].id, generate: orderId }, { extract: data[*].total, generate: amount }] }]。
39. 记住 [*] 通配符只在 lists[].fields[].extract 内生效；在顶层 fields[].extract 中，data[*].fieldName 以及裸 data[*] 会被静默忽略，字段永远不会合并到记录；裸结果字段名，不带 data 前缀的 fieldName，在两个 section 都解析不到。
40. 对 imports，response 通过 _json 可用，使用 _json.fieldName，如创建记录的 ID 用 _json.id，AI 模型响应用 _json.output.1.content.0.text。
41. 用 CLI 发现资源：celigo account search <keyword> 按名称查找 imports/exports；celigo imports get <importId> 检查现有 import，确认 mappings vs mapping；celigo exports get <exportId> 检查现有 export，确认 transform。
42. 用 CLI 理解数据形状：celigo exports invoke <exportId> 查看真实源记录；celigo metadata types <connectionId> 列出实体类型；celigo metadata fields <connectionId> <type> 列出实体字段。
43. 用 GET -> modify -> PUT 更新 mappings：celigo imports set <importId> <key>=<value> [<key2>=<value2> ...] 做字段级编辑，支持 dot/bracket paths 和 JSON values；celigo exports set <exportId> <key>=<value> ... 同理；celigo imports update <importId> < import.json 从 stdin JSON 做完整 PUT 替换；celigo exports update <exportId> < export.json 同理。
44. 提交前检查正确系统：Mapper 2.0 用 mappings[]，Mapper 1.0 用 mapping.fields[]，绝不要混用。
45. 提交前检查每个 mapping entry 都有 status: Active，否则 API 拒绝。
46. 提交前检查 generate 没有点号，嵌套对象用 dataType: object 加子 mappings[]。
47. 提交前检查 extract paths 从 root 开始，$. 路径始终引用顶层输入，即使嵌套 mapping。
48. 提交前检查所有 *array dataType 都有 buildArrayHelper。
49. 提交前检查每个 mapping 上的 lookupName 在 lookups[] 有对应条目。
50. 提交前检查 dataType: date 时设置 extractDateFormat/generateDateFormat。
51. 提交前完整 PUT：先 GET 完整资源，仅修改 mapping section，再 PUT 整个对象回去。
52. 提交前检查 response mapping 在 flow 的 pageProcessors[]，不在 import 资源本身。
53. 提交前检查 composite object paths：当 buildArrayHelper 同时有 extract 和 mappings 时，子 extract paths 去掉 [*] 方括号。
54. 处理 Gotcha：现有 imports 即使是 HTTP/RDBMS/FTP 也可能用 Mapper 1.0；编辑前总是检查格式，mappings[] 是 2.0，mapping.fields[] 是 1.0，绝不混用。
55. 处理 Gotcha：extract paths 总是引用 input context 的 root，即使深层嵌套 Mapper 2.0 mappings 也如此。
56. 处理 Gotcha：composite object 会把数组塌缩为单对象；当 buildArrayHelper 同时有 extract 和 mappings，子 mapping 上下文中数组方括号被替换为单对象。
57. 处理 Gotcha：response mapping 使用 Transformation 1.0 语法，不要用 rulesTwoDotZero 结构，只用简单 extract/generate 对加点号。
58. 处理 Gotcha：NetSuite lookups 查询实时数据，NetSuite import 的 netsuite_da.lookups[] 用 recordType、searchField、resultField 在运行时搜索记录，不同于 Mapper 2.0 静态 map lookup。
59. 处理 Gotcha：Mapper 2.0 的 generate 不能使用点号；generate: customer.name 会静默创建字面名为 customer.name 的字段。
60. 处理 Gotcha：arrayarray 中内层数组 mapping 的空 generate 是正常现象，不是错误。
61. 处理 Gotcha：Transformation 2.0 的 modify 模式会透传未映射字段；create 模式只输出显式映射字段；按目标选择。
62. 处理 Gotcha：PUT 会擦除父资源上省略的字段；更新 import mappings 或 export transform 时总是先 GET 完整资源，修改 mapping/transform section，再 PUT 完整对象；set 命令会处理这一点。
63. 处理 Gotcha：response mapping 中 [*] 只在 lists 内工作；顶层 fields[].extract 中的 data[*].fieldName 会被静默忽略；多结果用 extract: data 或带 data[*].fieldName extracts 的 lists 条目。
64. 修复常见错误：出现 Mapping object must have status field present 时，给每个 mapping object 添加 status: Active。
65. 修复常见错误：import 静默创建名为 customer.name 的字段时，去掉 generate 中的点号，改用嵌套 dataType: object 加子 mappings[]。
66. 修复常见错误：输出缺少 mapped fields 时，检查是否在 Mapper 1.0 import 上用了 Mapper 2.0 语法或反之；mappings[] 表示 2.0，mapping.fields[] 表示 1.0。
67. 修复常见错误：嵌套 mapping 中 extract 返回 null 时，改为从 root 开始的 extract path，即使用 $.，不要相对于当前嵌套层级。
68. 修复常见错误：数组输出为空时，为所有 *array dataType 添加 buildArrayHelper[]。
69. 修复常见错误：lookup key 未找到或处理停止时，在 lookup 上设置 allowFailures: true 并提供 default 值。
70. 修复常见错误：response mapping 未应用时，把 responseMapping 从 import 资源移到该 import 的 flow.pageProcessors[] 条目。
71. 修复常见错误：lookup response 字段为空或从未合并时，单结果用 data[0].fieldName；多结果用 extract: data 或带 data[*].fieldName extracts 的 lists 条目。
72. 修复常见错误：composite object paths 返回错误数据时，去掉子 extract paths 中的 [*] 方括号。
73. 修复常见错误：日期值输出格式错误时，在 date mappings 设置 extractDateFormat 和 generateDateFormat。
74. 修复常见错误：PUT 覆盖整个资源时，不要发送 partial JSON；总是先 GET 完整资源，修改 mapping section，再 PUT 完整对象。

适用边界 · 注意事项

• 不适用于非 Celigo 集成，或无法访问 Celigo 账号、CLI 与对应资源的环境。
• 不适用于在上游 export 用 transformation 去匹配下游目标形状；该场景应改为在目标 import 的 mapping 中处理。
• 不适用于没有 import、export、flow、pageProcessors 或 lookup 等 Celigo 资源上下文的通用数据转换。