sf-industry-commoncore-datamapper

sf-industry-commoncore-datamapper：OmniStudio Data Mapper 创建与验证

OmniStudio Data Mapper 专家开发者，专攻 Extract、Transform、Load 和 Turbo Extract 配置。生成可用于生产环境、性能出色且易于维护的 Data Mapper 定义，并进行恰当的字段映射、查询优化和数据完整性保护。

核心职责

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

---

重要：编排顺序

sf-industry-commoncore-omnistudio-analyze -> sf-industry-commoncore-datamapper -> sf-industry-commoncore-integration-procedure -> sf-industry-commoncore-omniscript -> sf-industry-commoncore-flexcard（当前位置：sf-industry-commoncore-datamapper）

Data Mapper 是 OmniStudio 技术栈的数据访问层。必须先创建并部署 Data Mapper，再创建引用它们的 Integration Procedures 或 OmniScripts。首先使用 sf-industry-commoncore-omnistudio-analyze 了解现有组件的依赖关系。

---

关键要点

要点	详情
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 执行插入、更新、插入或更新（upsert）或删除操作。它们需要适当的 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 及其相关 Contact
• DR_TurboExtract_Case_List -- 为 FlexCard 提供高容量 Case 列表
• DR_Transform_Lead_Flatten -- 扁平化嵌套的 Lead 数据结构
• DR_Load_Opportunity_Create -- 插入 Opportunity 记录

---

阶段 3：生成与验证

生成时：

1. 定义 OmniDataTransform 记录（名称、类型、启用状态）
2. 定义 OmniDataTransformItem 记录（字段映射、输入/输出路径）
3. 为 Extract 类型配置查询筛选条件、排序顺序和限制
4. 为 Load 类型设置查找映射和默认值
5. 验证所有映射字段的字段级安全性

审查时：

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

运行验证：

Score: XX/100 Rating
|- Design & Naming: XX/20
|- Field Mapping: XX/25
|- Data Integrity: XX/25
|- Performance: XX/15
|- Documentation: XX/15

---

生成防护措施（强制）

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

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

“我注意到 [pattern]。这会导致 [problem]。我应该： A) 重构为使用 [correct pattern] 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：验证 使用 sf-deploy 技能：“Deploy OmniDataTransform [Name] to [target-org] with --dry-run”

步骤 2：部署（仅在验证成功后） 使用 sf-deploy 技能：“Proceed with actual deployment to [target-org]”

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

---

阶段 5：测试与文档

完成摘要：

Data Mapper Complete: [Name]
  Type: [Extract|Transform|Load|Turbo Extract]
  Target Object(s): [Object1, Object2]
  Field Count: [N mapped fields]
  Validation: PASSED (Score: XX/100)

Next Steps: Test in Integration Procedure, verify data output, monitor performance

测试清单：

• 在 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" -o <org>

查询 Data Mapper 字段映射

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

获取 Data Mapper 元数据

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

部署 Data Mapper 元数据

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

---

跨技能集成

来源技能	目标 sf-industry-commoncore-datamapper	时机
sf-industry-commoncore-omnistudio-analyze	-> sf-industry-commoncore-datamapper	“创建 Data Mapper 前分析依赖项”
sf-metadata	-> sf-industry-commoncore-datamapper	“映射前描述目标对象字段”
sf-soql	-> sf-industry-commoncore-datamapper	“验证 Extract 查询逻辑”

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

---

边缘情况

场景	解决方案
大数据量（超过 10K 条记录）	使用 Turbo Extract；通过 Integration Procedure 添加分页；注意堆限制
多态查找字段	在映射中指定具体对象类型；分别测试每种类型
Extract 中的公式字段	标准 Extract 支持公式字段；Turbo Extract 不支持——改用标准 Extract
跨对象 Load（主从关系）	先插入父记录，再在单独的 Load 步骤中插入子记录；使用 Integration Procedure 编排顺序
带命名空间前缀的字段	在字段路径中包含命名空间前缀（例如，ns__Field__c）；确认前缀与目标组织一致
多币种组织	明确映射 CurrencyIsoCode；不要依赖默认币种假设
依赖 RecordType 的映射	在 Extract 中按 RecordType 筛选；在 Load 中设置 RecordTypeId；记录支持的 RecordType

---

说明

• 元数据类型：OmniDataTransform（不是 DataRaptor；旧名称已弃用）
• API 版本：需要 OmniStudio 托管包或 Industries Cloud
• 评分：分数低于 67 时阻止部署
• 依赖项（可选）：sf-deploy、sf-metadata、sf-industry-commoncore-omnistudio-analyze、sf-industry-commoncore-integration-procedure
• Turbo Extract 的限制：不支持公式字段、相关列表、聚合查询或多态字段
• 激活：部署后必须激活 Data Mapper，才能从 Integration Procedure 调用
• 无法检索草稿 DM：sf project retrieve start -m OmniDataTransform:<Name> 仅适用于已激活的 Data Mapper。草稿 DM 会返回“Entity cannot be found”。
• 通过 Data API 创建：使用 sf api request rest --method POST --body @file.json 创建 OmniDataTransform 和 OmniDataTransformItem 记录。sf data create record --values 标志无法处理 textarea 字段中的 JSON。请先将 JSON 请求体写入临时文件。
• 外键字段名称：OmniDataTransformItem 上的父级查找字段为 OmniDataTransformationId（完整单词“Transformation”），而不是 OmniDataTransformId。

---

许可证

MIT License。 版权所有 (c) 2026 David Ryan (weytani)