在 Salesforce OmniStudio…

当你需要创建或审查 OmniStudio Integration Procedure（组合 DataRaptor/Data Mapper、Apex Remote Action、HTTP callout、条件分支与嵌套 IP 的服务端流程编排）时使用。

适用场景

解决思路

1. 按 5 阶段流程执行：需求收集 → 设计与元素选择 → 生成与验证 → 部署 → 测试。
2. 需求收集阶段先评估替代方案：若只需单个 DataRaptor、Apex 服务或 Flow 即可完成，则不要用 IP；IP 适用于需要声明式多步编排、分支、错误处理和混合数据源的场景。
3. 向用户收集：要编排的业务目的与流程、目标对象与数据源（Salesforce 对象、外部 API 或两者）、Type/SubType 命名（如 Type=OrderProcessing、SubType=Standard）、目标 org alias。
4. 用 CLI 查询现有 IP，识别可复用的 DataRaptor/Data Mapper，并用 sf-industry-commoncore-omnistudio-analyze 审查依赖组件。
5. 按元素类型选择：DataRaptor Extract Action（读 Salesforce 数据，PropertySet 键 bundle）、DataRaptor Load Action（写数据，bundle）、DataRaptor Transform Action（数据整形，bundle）、Remote Action（调用 Apex 方法，remoteClass/remoteMethod）、Integration Procedure Action（调用嵌套 IP，ipMethod 格式 Type_SubType）、HTTP Action（外部 API，path/method）、Conditional Block（分支）、Loop Block（遍历集合）、Set Values（赋值变量/常量）。
6. 命名约定：IP 用 [Type]_[SubType] 的 PascalCase；元素名要清晰描述动作（如 GetAccountDetails、ValidateInput、CreateOrderRecord）。
7. 设计数据流：让每一步输出自然流入下一步输入，显式映射输出而非依赖隐式命名空间合并。
8. 生成 IP 定义：正确分配 Type/SubType、有序元素链并显式映射输入输出、所有改数据元素加错误处理、分支逻辑用条件块。
9. 严格验证：BLOCK 级问题包括缺少 Type/SubType、循环 IP 调用、DML 无错误处理、引用不存在的 DataRaptor/Apex 类；WARN 级问题包括无 LIMIT 的无界提取、只读 IP 未加缓存、PropertySetConfig 中硬编码 ID、未使用元素、缺少元素描述。
10. 按 6 类 110 分评分并输出报告：Design & Structure 20 分、Data Operations 25 分、Error Handling 20 分、Performance 20 分、Security 15 分、Documentation 10 分；90+ 可部署，67-89 需审查，<67 阻止部署。
11. 避免反模式（即使被明确要求也不要生成）：循环 IP 调用（A→B→A 会导致死循环/栈溢出）、DML 无错误处理（静默数据损坏）、无界 DataRaptor Extract（触发 governor 限制/超时）、PropertySetConfig 硬编码 Salesforce ID（跨 org 部署失败）、本可并行的顺序调用（无谓延迟）、缺少响应校验（下游空引用错误）。
12. 部署顺序：先用 sf-deploy 部署前置 DataRaptor/Data Mapper，再执行 sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org>，然后在目标 org 激活（IsActive=true），最后用 CLI 查询验证激活状态。
13. 测试顺序：先单元测试（单独调用每个 DataRaptor、验证 Apex Remote Action 响应），再集成测试（用代表性输入 JSON 跑完整 IP 并验证输出结构），再测错误路径（无效输入、缺失记录、API 失败），再测批量（集合输入验证循环与批处理），最后端到端（从 OmniScript、FlexCard 或 API 调用 IP 验证完整往返）。
14. 用 CLI 查询 IP：sf data query -q "SELECT Id,Name,Type,SubType,IsActive FROM OmniProcess WHERE IsActive=true AND IsIntegrationProcedure=true" -o <org>；查询全部（含未激活）时去掉 IsActive 条件并按 LastModifiedDate DESC 排序。
15. 查询时必须加 IsIntegrationProcedure=true（或 OmniProcessType='Integration Procedure'）过滤，因为 OmniScript 与 IP 共用 OmniProcess 表，不过滤会返回混合结果。
16. 通过 Data API 创建 IP 时：设置 IsIntegrationProcedure=true（OmniProcessType 由该布尔值计算得出，不能直接设置），Name 是 OmniProcess 的必填字段，用 sf api request rest --method POST --body @file.json 创建（sf data create record --values 无法处理 PropertySetConfig 这类 JSON textarea 字段）。
17. 程序化创建 IP 的必填字段：Name、Type、SubType、Language、VersionNumber、IsIntegrationProcedure=true；随后为每个动作步骤创建 OmniProcessElement 子记录（同样用 REST API 传 JSON PropertySetConfig），全部元素创建完成后再设 IsActive=true 激活。
18. 处理边界情况：直接/间接递归用调用图检测并阻止；DataRaptor 未部署则先部署；外部 API 超时则设置 HTTP Action 超时并实现重试或优雅降级；Loop Block 大集合输入要设批大小并用真实数据量测试避免 CPU 超时；Type/SubType 冲突则先查询现有 IP 并用 SubType 版本化；混合命名空间（Vlocity vs Core）先确认 org 命名空间，元素属性名在两包间不同。
19. 调试：IP 不执行→检查 IsActive 标志与 Type/SubType 匹配；元素被跳过→检查条件块逻辑与输入数据形状；超时→检查 DataRaptor 查询范围与 HTTP 超时设置；部署失败→确认所有引用组件已部署且激活。

适用边界 · 注意事项

• 构建 OmniScript 时应使用 sf-industry-commoncore-omniscript，而不是本技能。
• 直接创建 Data Mapper 时应使用 sf-industry-commoncore-datamapper，而不是本技能。
• 分析跨组件依赖时应使用 sf-industry-commoncore-omnistudio-analyze，而不是本技能。