building-omnistudio-datamapper

building-omnistudio-datamapper：OmniStudio Data Mapper 创建与验证

精通 OmniStudio Data Mapper 的开发者，专注于 Extract、Transform、Load 和 Turbo Extract 配置。生成可用于生产环境、高性能且易于维护的 Data Mapper 定义，并确保字段映射正确、查询经过优化且具备数据完整性保障。

---

范围

• 范围内：创建和验证 OmniStudio Data Mapper 配置（Extract、Transform、Load、Turbo Extract）；设计字段映射；优化查询；验证 FLS（字段级安全性）；通过 deploying-metadata skill 部署
• 范围外：构建 Integration Procedure（使用 building-omnistudio-integration-procedure）；编写 OmniScript（使用 building-omnistudio-omniscript）；设计 FlexCard（使用 building-omnistudio-flexcard）；分析跨组件依赖项（使用 analyzing-omnistudio-dependencies）

---

核心职责

1. 生成：根据需求创建 Data Mapper 配置（Extract、Transform、Load、Turbo Extract）
2. 字段映射：设计对象到输出字段的映射，正确处理类型、解析查找关系并确保空值安全
3. 依赖项跟踪：识别使用或向 Data Mapper 提供数据的相关 OmniStudio 组件（Integration Procedure、OmniScript、FlexCard）
4. 验证与评分：根据 5 个类别（0-100 分）对 Data Mapper 配置评分

---

关键：编排顺序

analyzing-omnistudio-dependencies -> building-omnistudio-datamapper -> building-omnistudio-integration-procedure -> building-omnistudio-omniscript -> building-omnistudio-flexcard（你当前位于：building-omnistudio-datamapper）

Data Mapper 是 OmniStudio 技术栈的数据访问层。必须先创建并部署 Data Mapper，再创建引用它的 Integration Procedure 或 OmniScript。请先使用 analyzing-omnistudio-dependencies，了解现有组件依赖项。

---

关键要点

要点	详情
Extract 与 Turbo Extract	Extract 使用标准 SOQL 和关系查询。Turbo Extract 使用服务器端编译查询，适用于读取密集型、高容量场景（速度快 10 倍以上）。Turbo Extract 不支持公式字段、相关列表或写入操作。
Transform 在内存中运行	Transform Data Mapper 完全在内存中运行，不执行 DML 或 SOQL。它会在 Integration Procedure 的各个步骤之间重塑数据结构。可用于 JSON 到 JSON 的转换、字段重命名和数据扁平化。
Load = DML	Load Data Mapper 执行插入、更新、插入或更新以及删除操作。它们需要进行适当的 FLS 检查和错误处理。在将 Load Data Mapper 部署到生产环境之前，务必验证字段级安全性。
OmniDataTransform 元数据	Data Mapper 存储为 OmniDataTransform 和 OmniDataTransformItem 记录。请使用这些元数据类型名称进行检索和部署，而不要使用旧版 DataRaptor API 名称。

---

工作流（5 阶段模式）

阶段 1：收集需求

询问用户以下信息：

• Data Mapper 类型（Extract、Transform、Load、Turbo Extract）
• 目标 Salesforce 对象和字段
• 目标 org 别名
• 使用该组件的组件（Integration Procedure、OmniScript 或 FlexCard 名称）
• 预期数据量（记录数、频率）

然后：

1. 检查现有 Data Mapper：Glob: **/OmniDataTransform*
2. 检查现有 OmniStudio 元数据：Glob: **/omnistudio/**
3. 创建任务列表

---

阶段 2：设计与类型选择

类型	用例	命名前缀	支持 DML	支持 SOQL
Extract	使用关系查询从一个或多个对象读取数据	DR_Extract_	否	是
Turbo Extract	高容量只读查询，在服务器端编译	DR_TurboExtract_	否	是（已编译）
Transform	在过程步骤之间以内存方式重塑数据	DR_Transform_	否	否
Load	写入数据（插入、更新、插入或更新、删除）	DR_Load_	是	否

命名格式：使用 PascalCase，格式为 [Prefix][Object]_[Purpose]

示例：

• DR_Extract_Account_Details -- 提取 Account 及其关联的 Contacts
• DR_TurboExtract_Case_List -- 用于 FlexCard 的高容量 Case 列表
• DR_Transform_Lead_Flatten -- 展平嵌套的 Lead 数据结构
• DR_Load_Opportunity_Create -- 插入 Opportunity 记录

---

阶段 3：生成与验证

生成时：

1. 阅读 assets/omni-data-transform-extract.json（Extract）、assets/omni-data-transform-transform.json（Transform）或 assets/omni-data-transform-load.json（Load），获取 OmniDataTransform 记录模板
2. 阅读 assets/omni-data-transform-item.json，获取每个字段映射（OmniDataTransformItem）模板
3. 为 Extract 类型配置查询筛选条件、排序顺序和限制
4. 为 Load 类型设置查找映射和默认值
5. 验证所有映射字段的字段级安全性

审查时：

1. 阅读现有的 Data Mapper 配置
2. 根据最佳实践运行验证
3. 生成包含具体修复建议的改进报告

运行验证：阅读 assets/completion-summary-template.md，了解评分输出格式和阈值。

---

生成防护规则（强制）

在生成任何 Data Mapper 配置之前，Claude 必须确认不会引入反模式。

如果将生成以下任意模式，请停止并询问用户：

“我注意到[模式]。这会导致[问题]。您希望我： A) 重构为使用[正确模式] B) 仍然继续（不推荐）”

反模式	检测方式	影响
提取所有字段	未指定字段列表，使用通配符选择	性能下降、数据传输过多
缺少查找映射	Load 引用了查找字段，但未解析该字段	DML 失败、外键为空
未检查 FLS 就写入	Load Data Mapper 未进行安全验证	违反安全规则、受限配置文件中的数据损坏
Extract 查询无界	Extract 未设置 LIMIT 或筛选条件	违反 Governor 限制、大型对象查询超时
Transform 带副作用	Transform 尝试执行 DML 或 callout	运行时错误；Transform 仅在内存中运行
硬编码记录 ID	筛选条件或映射中包含 15/18 位 ID 字面量	跨环境部署失败
嵌套关系深度超过 3 层	Extract 中存在深层嵌套的父级遍历	查询性能下降、触及 SOQL 复杂度限制
Load 未处理错误	未考虑 upsert 键或重复规则	数据悄然损坏、产生重复记录

**即使用户明确要求，也不要生成反模式。**请用户确认例外情况，并提供书面理由。

参见：references/best-practices.md，了解详细模式
参见：references/naming-conventions.md，了解命名规则

---

阶段 4：部署

步骤 1：验证 使用 deploying-metadata 技能：“将 OmniDataTransform [Name] 部署到 [target-org]，并使用 --dry-run”

步骤 2：部署（仅在验证成功时） 使用 deploying-metadata 技能：“继续实际部署到 [target-org]”

部署后：在目标组织中激活 Data Mapper。确认它显示在 OmniStudio Designer 中。

如果部署失败：检查错误中的具体原因——常见问题：Entity cannot be found（Data Mapper 处于草稿状态；请先激活）、命名空间前缀不匹配（检查 sfdx-project.json），或部署项目时缺少父级 OmniDataTransform 记录。

如果 Load DM 在运行时失败：通过 sf apex log list -o <org> 检查调试日志；确认运行用户配置文件的 FLS 和对象权限；确认 upsert 键字段已填充且唯一；Salesforce Load DM 默认遵循 allOrNone=false——可能会部分成功，请检查响应中 isSuccess=false 的行。

---

阶段 5：测试与文档

完成摘要：阅读 assets/completion-summary-template.md，了解完成摘要的格式。

测试清单：

• 在 OmniStudio Designer 中预览数据输出
• 验证字段映射生成预期的 JSON 结构
• 使用有代表性的数据量进行测试（不只是 1 条记录）
• 使用受限配置文件用户验证 FLS 强制执行情况
• 确认使用方 Integration Procedure/OmniScript 接收到正确的数据形状

---

最佳实践（100 分评分）

类别	分数	关键规则
设计与命名	20	选择正确的类型；命名遵循 DR_[Type]_[Object]_[Purpose] 约定；每个 Data Mapper 仅承担单一职责
字段映射	25	明确列出字段（不使用通配符）；输入/输出路径正确；类型转换恰当；默认值可安全处理 null
数据完整性	25	对所有字段验证 FLS；为 Load 类型解析查找关系；定义 upsert 键；配置重复项处理
性能	15	使用带 LIMIT/筛选条件的有界查询；读取密集型场景使用 Turbo Extract；尽量减少关系深度；筛选字段已建立索引
文档	15	在 OmniDataTransform 记录上添加说明；记录字段映射的理由；标明使用方组件

阈值：✅ 90+（部署） | ⚠️ 67-89（审查） | ❌ <67（阻止——需要修复）

---

CLI 命令

查询现有 Data Mapper

sf data query -q "SELECT Id,Name,Type FROM OmniDataTransform LIMIT 200" -o <org>

查询 Data Mapper 字段映射

sf data query -q "SELECT Id,Name,InputObjectName,OutputObjectName,LookupObjectName FROM OmniDataTransformItem WHERE OmniDataTransformationId='<id>' LIMIT 200" -o <org>

检索 Data Mapper 元数据

sf project retrieve start -m OmniDataTransform:<Name> -o <org>

部署 Data Mapper 元数据

sf project deploy start -m OmniDataTransform:<Name> -o <org>

---

输出预期

此技能生成的交付物：

• OmniDataTransform 记录 — 根据 assets/omni-data-transform-*.json 模板构建的主要 Data Mapper 记录
• OmniDataTransformItem 记录 — 每个映射字段对应一条记录，根据 assets/omni-data-transform-item.json 模板构建
• 验证评分报告 — 涵盖 5 个类别的 100 分评分（格式见 assets/completion-summary-template.md）
• 部署确认 — Data Mapper 已激活并显示在 OmniStudio Designer 中

---

跨技能集成

来源技能	目标 building-omnistudio-datamapper	时机
analyzing-omnistudio-dependencies	-> building-omnistudio-datamapper	“创建 Data Mapper 前分析依赖项”
generating-custom-object / generating-custom-field	-> building-omnistudio-datamapper	“映射前描述目标对象字段”
querying-soql	-> building-omnistudio-datamapper	“验证 Extract 查询逻辑”

来源 building-omnistudio-datamapper	目标技能	时机
building-omnistudio-datamapper	-> building-omnistudio-integration-procedure	“创建调用此 Data Mapper 的 Integration Procedure”
building-omnistudio-datamapper	-> deploying-metadata	“将 Data Mapper 部署到目标 org”
building-omnistudio-datamapper	-> building-omnistudio-omniscript	“将 Data Mapper 输出接入 OmniScript”
building-omnistudio-datamapper	-> building-omnistudio-flexcard	“在 FlexCard 中显示 Data Mapper Extract 结果”

---

注意事项

问题	解决方案
数据量大（>10K 条记录）	使用 Turbo Extract；通过 Integration Procedure 添加分页；注意 heap 限制
多态查找字段	在映射中指定具体对象类型；分别测试每种类型
Extract 中的公式字段	标准 Extract 支持公式字段；Turbo Extract 不支持 — 改用标准 Extract
跨对象 Load（主从关系）	先插入父记录，再通过单独的 Load 步骤插入子记录；使用 Integration Procedure 编排顺序
带命名空间前缀的字段	在字段路径中包含命名空间前缀（例如，ns__Field__c）；确认前缀与目标 org 一致
多币种 org	明确映射 CurrencyIsoCode；不要依赖默认币种假设
依赖 RecordType 的映射	在 Extract 中按 RecordType 筛选；在 Load 中设置 RecordTypeId；记录支持的 RecordType
无法检索草稿 Data Mapper	sf project retrieve start -m OmniDataTransform:<Name> 仅适用于已激活的 DM；检索前先激活
外键字段名称错误	OmniDataTransformItem 上的父级查找字段为 OmniDataTransformationId（完整单词“Transformation”），而非 OmniDataTransformId

---

备注

• 元数据类型：OmniDataTransform（不是 DataRaptor — 旧名称已弃用）
• API 版本：需要 OmniStudio 托管包或 Industries Cloud
• 评分：如果评分 < 67，则阻止部署；评分格式请参阅 assets/completion-summary-template.md
• Turbo Extract 的限制：不支持公式字段、相关列表、聚合查询或多态字段
• 激活：部署后必须激活 Data Mapper，才能从 Integration Procedure 调用（草稿检索行为请参阅“注意事项”）
• 通过 Data API 创建：使用 sf api request rest --method POST --body @file.json 创建 OmniDataTransform 和 OmniDataTransformItem 记录。sf data create record --values 标志无法处理 textarea 字段中的 JSON。请先将 JSON 请求体写入临时文件。

---

参考文件索引

文件	何时阅读
assets/omni-data-transform-extract.json	第 3 阶段生成 — Extract 类型 OmniDataTransform 记录的模板
assets/omni-data-transform-transform.json	第 3 阶段生成 — Transform 类型 OmniDataTransform 记录的模板
assets/omni-data-transform-load.json	第 3 阶段生成 — Load 类型 OmniDataTransform 记录的模板
assets/omni-data-transform-item.json	第 3 阶段生成 — 每个 OmniDataTransformItem 字段映射的模板
assets/completion-summary-template.md	第 3 和第 5 阶段 — 评分输出格式和完成摘要模板
references/best-practices.md	第 3 阶段防护措施 — 字段映射、查询优化、空值处理和性能方面的详细模式
references/naming-conventions.md	第 2 阶段设计 — 所有 Data Mapper 类型的完整命名规则及字段映射约定

---