sf-industry-commoncore-datamapper

用途

本技能面向 Salesforce OmniStudio Data Mapper（原 DataRaptor）的开发与验证，专注于 Extract（抽取）、Transform（转换）、Load（加载）与 Turbo Extract（高性能抽取）四类配置的生成与检查。Data Mapper 是 OmniStudio 技术栈中的数据访问层，必须先于引用它的 Integration Procedure 或 OmniScript 创建并部署。

主要能力

生成（Generation）：根据需求创建 Extract、Transform、Load、Turbo Extract 配置。
字段映射（Field Mapping）：设计对象到输出的字段映射，处理类型转换、lookup 解析与空值安全。
依赖跟踪（Dependency Tracking）：识别相关的 OmniStudio 组件（Integration Procedure、OmniScript、FlexCard）——它们消费或向上游提供 Data Mapper 数据。
校验与评分（Validation & Scoring）：按 5 个类别对配置进行 0–100 评分。

关键要点

Extract 与 Turbo Extract：Extract 使用标准 SOQL 与关系查询；Turbo Extract 使用服务端编译查询，适用于读多、高并发场景（快 10 倍以上），但不支持公式字段、相关列表或写操作。
Transform 在内存中执行：无 DML 或 SOQL，用于在 Integration Procedure 步骤之间重塑数据结构，如 JSON 到 JSON 转换、字段重命名、数据扁平化。
Load 即 DML：执行 insert、update、upsert 或 delete，需要 FLS 检查与错误处理，部署到生产前须验证字段级安全。
元数据类型：Data Mapper 存储为 OmniDataTransform 与 OmniDataTransformItem 记录，应使用这些元数据类型名称检索和部署，而非已弃用的 DataRaptor API 名称。

编排顺序

sf-industry-commoncore-omnistudio-analyze → sf-industry-commoncore-datamapper → sf-industry-commoncore-integration-procedure → sf-industry-commoncore-omniscript → sf-industry-commoncore-flexcard（本技能位于第二步）。建议先用 omnistudio-analyze 了解已有组件依赖。

使用方式（5 阶段工作流）

阶段 1：需求收集——收集 Data Mapper 类型、目标对象与字段、目标 org 别名、消费组件名称、数据量预期；然后检查已有 Data Mapper（Glob: */OmniDataTransform）、检查已有 OmniStudio 元数据（Glob: /omnistudio/）、创建任务列表。

阶段 2：设计与类型选择——按用途选择类型与命名前缀：

Extract / DR_Extract_ / 支持 SOQL、不支持 DML
Turbo Extract / DR_TurboExtract_ / 支持编译 SOQL、不支持 DML
Transform / DR_Transform_ / 无 SOQL、无 DML
Load / DR_Load_ / 支持 DML、无 SOQL 命名格式为 [Prefix][Object]_[Purpose]，采用 PascalCase，例如 DR_Extract_Account_Details、DR_Load_Opportunity_Create。

阶段 3：生成与校验——生成时定义 OmniDataTransform 记录与 OmniDataTransformItem 记录，配置查询过滤、排序与限制，设置 lookup 映射与默认值，并验证所有映射字段的字段级安全。评分维度为：设计与命名 20 分、字段映射 25 分、数据完整性 25 分、性能 15 分、文档 15 分；90+ 可部署，67–89 需复查，低于 67 阻止部署。

阶段 4：部署——先用 sf-deploy 做 --dry-run 验证，成功后执行实际部署，部署后在目标 org 激活 Data Mapper 并确认其出现在 OmniStudio Designer 中。

阶段 5：测试与文档——输出完成摘要（名称、类型、目标对象、字段数、校验分数），在 Integration Procedure 中测试、核对数据输出与性能，并检查：预览数据输出、验证 JSON 结构、用有代表性的数据量测试、用受限 profile 验证 FLS、确认消费组件收到正确数据形态。

生成护栏（强制）

生成配置前必须确认不引入反模式；若将生成以下模式必须停下并询问用户：抽取所有字段（未指定字段列表/通配选择）、缺失 lookup 映射、未做 FLS 检查就写入、无界 Extract 查询（无 LIMIT 或过滤）、Transform 带副作用（尝试 DML 或 callout）、硬编码记录 ID、嵌套关系深度 >3、Load 无错误处理（无 upsert 键或重复规则考虑）。即使用户明确要求，也不得生成这些反模式，须让用户确认例外并附书面理由。

CLI 命令

查询已有 Data Mapper：sf data query -q "SELECT Id,Name,Type FROM OmniDataTransform" -o <org>
查询字段映射：sf data query -q "SELECT Id,Name,InputObjectName,OutputObjectName,LookupObjectName FROM OmniDataTransformItem WHERE OmniDataTransformationId='<id>'" -o <org>
检索元数据：sf project retrieve start -m OmniDataTransform:<Name> -o <org>
部署元数据：sf project deploy start -m OmniDataTransform:<Name> -o <org>

跨技能集成

上游来源：omnistudio-analyze（创建前分析依赖）、sf-metadata（映射前描述目标对象字段）、sf-soql（校验 Extract 查询逻辑）。下游去向：integration-procedure（创建调用该 Data Mapper 的流程）、sf-deploy（部署）、omniscript（接入输出）、flexcard（展示 Extract 结果）。

边界情况

大数据量（>10K 记录）：用 Turbo Extract，通过 Integration Procedure 分页，关注堆限制。
多态 lookup 字段：在映射中指定具体对象类型，逐类型测试。
Extract 中的公式字段：标准 Extract 支持，Turbo Extract 不支持，需回退到标准 Extract。
跨对象 Load（主从）：先插父记录再单独插入子记录，用 Integration Procedure 编排顺序。
带命名空间前缀的字段：字段路径含命名空间前缀（如 ns__Field__c），确认前缀与目标 org 匹配。
多币种 org：显式映射 CurrencyIsoCode。
依赖 RecordType 的映射：在 Extract 中按 RecordType 过滤，在 Load 中设置 RecordTypeId，并记录支持的 RecordType。

限制与注意事项

元数据类型为 OmniDataTransform（DataRaptor 为已弃用旧名）。
需要 OmniStudio 托管包或 Industries Cloud。
评分低于 67 阻止部署。
Turbo Extract 限制：不支持公式字段、相关列表、聚合查询、多态字段。
部署后必须激活 Data Mapper 才能被 Integration Procedure 调用。
草稿 DM 无法检索：sf project retrieve start -m OmniDataTransform:<Name> 仅对已激活的 Data Mapper 有效，草稿会返回 “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 上的父 lookup 是 OmniDataTransformationId（完整词 “Transformation”），不是 OmniDataTransformId。
依赖（可选）：sf-deploy、sf-metadata、sf-industry-commoncore-omnistudio-analyze、sf-industry-commoncore-integration-procedure。