building-omnistudio-integration-procedure

building-omnistudio-integration-procedure：OmniStudio 集成过程的创建与验证

OmniStudio 集成过程（IP）构建专家，深入掌握服务器端流程编排。创建可用于生产环境的 IP，将 DataRaptor/Data Mapper 操作、Apex Remote Action、HTTP 调用、条件逻辑和嵌套过程调用组合为声明式多步骤操作。

范围

• 范围内：根据需求创建结构良好的集成过程；选择并连接元素类型（DataRaptor、Remote Action、HTTP、Conditional Block、Loop、Set Values、嵌套 IP）；验证依赖项；错误处理模式；110 分制评分；部署与激活
• 范围外：构建 OmniScripts（使用 building-omnistudio-omniscript）、直接创建 Data Mapper（使用 building-omnistudio-datamapper）、设计 FlexCard（使用 building-omnistudio-flexcard）、映射完整依赖树（使用 analyzing-omnistudio-dependencies）、将元数据部署到组织（使用 deploying-metadata）

---

必需输入

• 用途：此 IP 编排什么业务流程？（例如，“为新账户办理开户”，“处理订单”）
• 目标对象 / 数据源：涉及哪些 Salesforce 对象、外部 API，或两者兼有？
• Type / SubType 命名：用于唯一标识 IP 的 PascalCase 名称对（例如，Type=OrderProcessing、SubType=Standard）
• 目标组织别名：用于部署的已认证组织别名（例如，myDevOrg）

---

快速参考

评分：6 个类别，共 110 分。阈值：✅ 90 分以上（部署）| ⚠️ 67–89 分（审核）| ❌ 低于 67 分（阻止——必须修复）

---

核心职责

1. IP 生成：根据需求创建结构良好的集成过程，选择正确的元素类型并连接输入 / 输出
2. 元素组合：将 DataRaptor 操作、Remote Action、HTTP 调用、条件块、循环和嵌套 IP 调用组装成连贯的编排流程
3. 依赖项分析：部署前验证所引用的 DataRaptor、Apex 类和嵌套 IP 是否存在且处于激活状态
4. 错误处理：在所有数据修改步骤中强制执行 try/catch 模式、条件回滚和响应验证（DML——数据操纵语言）

---

关键：编排顺序

analyzing-omnistudio-dependencies -> building-omnistudio-datamapper -> building-omnistudio-integration-procedure -> building-omnistudio-omniscript -> building-omnistudio-flexcard（你正在这里：building-omnistudio-integration-procedure）

IP 引用的 Data Mapper 必须先存在。请先构建并部署 DataRaptor/Data Mapper，再构建调用它们的 IP。IP 必须处于激活状态，OmniScript 或 FlexCard 才能调用它。

---

关键要点

要点	详情
链式调用	IP 通过 Integration Procedure Action 元素调用其他 IP。某一步的输出通过响应映射作为下一步的输入。尽可能按线性方式设计数据流。
响应映射	每个元素的输出都会以该元素名称作为命名空间，存储在响应 JSON 中。使用 %elementName:keyPath% 语法，在下游输入中引用上游输出。
缓存	IP 支持平台缓存，适用于读取密集型编排。在过程的 PropertySet 中设置 cacheType 和 cacheTTL。避免缓存执行 DML 的过程。
版本控制	Type/SubType 组合可唯一标识一个 IP。使用 SubType 进行版本控制（例如，Type=AccountOnboarding、SubType=v2）。每个 Type/SubType 同一时间只能有一个活动版本。

Core 命名空间判别符：OmniStudio Core 将 Integration Procedure 和 OmniScript 都存储在 OmniProcess 表中。使用 IsIntegrationProcedure = true 或 OmniProcessType = 'Integration Procedure' 筛选 IP。若不添加筛选条件，查询结果会混杂两种类型。

重要 — 通过 Data API 创建 IP：创建 OmniProcess 记录时，设置 IsIntegrationProcedure = true，以便将记录创建为 Integration Procedure。OmniProcessType 选项列表由此布尔值计算得出，不能直接设置。此外，Name 是 OmniProcess 上的必填字段（标准 OmniStudio 文档中未说明）。使用 sf api request rest --method POST --body @file.json 创建记录——sf data create record --values 标志无法处理 PropertySetConfig 这类 JSON 文本区域字段。

---

工作流设计（5 阶段模式）

阶段 1：收集需求

开始构建前，先评估替代方案：有时，单个 DataRaptor、Apex 服务或 Flow 会是更合适的选择。当你需要通过声明式方式编排多个步骤，并包含分支、错误处理和混合数据源时，IP 是最佳选择。

向用户询问以下信息：

• 要编排的用途和业务流程
• 目标对象和数据源（Salesforce 对象、外部 API，或两者）
• Type/SubType 命名（例如，Type=OrderProcessing、SubType=Standard）
• 部署目标组织的别名

然后：通过 CLI 查询检查现有 IP（参见下方的 CLI 命令），找出可复用的 DataRaptor/Data Mapper，并使用 analyzing-omnistudio-dependencies 检查依赖组件。

阶段 2：设计和选择元素

元素类型	用例	PropertySet 键
DataRaptor Extract Action	读取 Salesforce 数据	bundle
DataRaptor Load Action	写入 Salesforce 数据	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	赋值变量/常量	--

命名约定：使用 PascalCase 格式的 [Type]_[SubType]。IP 中的元素名称应清楚描述其操作（例如，GetAccountDetails、ValidateInput、CreateOrderRecord）。

数据流：设计元素链，使每一步的输出都能自然地作为下一步的输入。明确映射输出，不要依赖隐式命名空间合并。

第 3 阶段：生成与验证

构建 IP 定义时，需包含：

• 正确分配 Type/SubType
• 按顺序排列的元素链，并明确映射输入/输出
• 为所有修改数据的元素设置错误处理
• 用于分支逻辑的条件块

验证（严格模式）：

• 阻止：缺少 Type/SubType、循环调用 IP、DML 操作没有错误处理、引用不存在的 DataRaptors/Apex 类
• 警告：无 LIMIT 的无限制提取、只读 IP 缺少缓存、PropertySetConfig 中存在硬编码 ID、未使用的元素、缺少元素说明

验证报告格式（6 类评分，总分 110）：确切的输出布局请参阅 assets/scoring-report-format.txt。

生成护栏（必须遵守）

反模式	影响	正确做法
循环调用 IP（A 调用 B，B 又调用 A）	无限循环 / 堆栈溢出	映射依赖关系图；不允许出现循环
DML 操作没有错误处理	数据静默损坏	将 DataRaptor Load 包装在 try/catch 中，或使用条件错误检查
无限制的 DataRaptor Extract	Governor 限制 / 超时	为提取设置 LIMIT；对大型数据集进行分页
PropertySetConfig 中存在硬编码的 Salesforce ID	跨组织部署失败	使用输入变量、自定义设置或自定义元数据
可并行执行的调用却按顺序执行	不必要的延迟	将相互独立的元素分组；避免不必要的串行依赖
缺少响应验证	下游出现空引用错误	在将元素响应传递给下一步前进行检查

即使明确提出要求，也不得生成反模式。

第 4 阶段：部署

1. 首先使用 deploying-metadata 部署前置 DataRaptors/Data Mappers
2. 部署 Integration Procedure：sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org>
3. 在目标组织中激活 IP（设置 IsActive=true）
4. 通过 CLI 查询验证激活状态

第 5 阶段：测试

在测试完整链路之前，先单独测试每个元素：

1. 单元测试：分别调用每个 DataRaptor，验证 Apex Remote Action 响应
2. 集成测试：使用有代表性的输入 JSON 运行完整 IP，验证输出结构
3. 错误路径：使用无效输入、缺失记录和 API 故障进行测试，以验证错误处理
4. 批量测试：使用集合输入进行测试，以验证循环和批处理行为
5. 端到端测试：从其调用方（OmniScript、FlexCard 或 API）调用 IP，并验证完整往返流程

---

评分细则

6 个类别总计 110 分：

设计与结构（20 分）

标准	分值	说明
Type/SubType 命名	5	遵循命名约定、描述清晰，并适当进行版本控制
元素命名	5	所有元素的名称清晰且以动作为导向
数据流清晰度	5	流程线性，或分支有完善文档；明确映射输入/输出
元素顺序	5	执行顺序合乎逻辑；不存在不必要的依赖关系

数据操作（25 分）

标准	分值	说明
DataRaptor 引用有效	5	所有引用的捆绑包均存在且处于激活状态
提取操作有界	5	所有提取均设置 LIMIT；大型数据集采用分页
加载操作经过验证	5	DML 前验证输入数据；检查必填字段
响应映射正确	5	元素间的输出映射正确
数据转换准确	5	转换操作生成符合预期的输出结构

错误处理（20 分）

标准	分值	说明
DML 错误处理	8	所有 DataRaptor Load 操作均设置错误处理
HTTP 错误处理	4	所有 HTTP 操作均检查状态码并处理故障
Remote Action 错误处理	4	捕获并传递 Apex 异常
回滚策略	4	多步骤 DML 设置条件回滚或补偿操作

性能（20 分）

标准	分值	说明
无无界查询	5	所有提取操作都有合理的 LIMIT 值
应用缓存	5	只读过程在适当情况下使用平台缓存
并行执行	5	不必要时不串行执行独立元素
无冗余调用	5	不会在多个元素中重复获取相同数据

安全性（15 分）

标准	分值	说明
无硬编码 ID	5	ID 作为输入变量传入或从元数据获取
无硬编码凭据	5	API 密钥/令牌使用 Named Credentials 或 Custom Settings
输入验证	5	使用用户提供的输入执行查询或 DML 前，先对其进行清理

文档（10 分）

标准	分值	说明
过程说明	3	清楚说明用途和业务背景
元素说明	4	每个元素都有说明，解释其作用
输入/输出文档	3	记录预期的输入 JSON 和输出 JSON 结构

---

CLI 命令

在查询或部署 Integration Procedures 之前，请阅读 scripts/cli-commands.sh；其中包含可直接调整使用的所有 SOQL 查询以及 sf project 部署/检索命令。

核心命名空间说明：必须使用 IsIntegrationProcedure=true 过滤条件（或等效的 OmniProcessType='Integration Procedure'）。OmniScript 和 Integration Procedure 记录共用 OmniProcess sObject。没有此过滤条件时，查询会返回这两种类型，导致结果产生误导。

---

跨技能集成

来源技能	目标：building-omnistudio-integration-procedure	时机
analyzing-omnistudio-dependencies	-> building-omnistudio-integration-procedure	“构建 IP 前分析依赖项”
building-omnistudio-datamapper	-> building-omnistudio-integration-procedure	“DataRaptor/Data Mapper 已就绪，将其接入 IP”
generating-apex	-> building-omnistudio-integration-procedure	“Apex Remote Action 类已部署，在 IP 中进行配置”

来源：building-omnistudio-integration-procedure	目标技能	时机
building-omnistudio-integration-procedure	-> deploying-metadata	“将 IP 部署到目标 org”
building-omnistudio-integration-procedure	-> building-omnistudio-omniscript	“IP 已激活，构建调用它的 OmniScript”
building-omnistudio-integration-procedure	-> building-omnistudio-flexcard	“IP 已激活，构建 FlexCard 数据源”
building-omnistudio-integration-procedure	-> analyzing-omnistudio-dependencies	“部署前验证 IP 依赖关系图”

---

边缘情况

场景	解决方案
IP 调用自身（直接递归）	在设计时阻止；必须检查循环依赖
IP 调用另一个会调用原 IP 的 IP（间接递归）	绘制完整调用图；analyzing-omnistudio-dependencies 可检测循环
DataRaptor 尚未部署	先部署 DataRaptor；缺少引用会导致 IP 部署失败
外部 API 超时	为 HTTP Action 元素设置超时值；实现重试逻辑或优雅降级
Loop Block 输入集合过大	设置批次大小；使用符合实际的数据量进行测试，避免 CPU 超时
与现有 IP 的 Type/SubType 冲突	创建前查询现有 IP；使用 SubType 版本控制以避免冲突
混合命名空间（Vlocity 与 Core）	确认 org 命名空间；不同包中的元素属性名称有所不同

调试：IP 未执行 -> 检查 IsActive 标记 + Type/SubType 是否匹配 | 元素被跳过 -> 验证条件块逻辑 + 输入数据形状 | 超时 -> 检查 DataRaptor 查询范围 + HTTP 超时设置 | 部署失败 -> 验证所有引用的组件均已部署并处于活动状态

---

输出预期

此技能生成的交付内容：

• 集成过程 JSON（assets/omni-process-ip.json 模板）——可通过 REST API 创建的 OmniProcess 记录，且 IsIntegrationProcedure=true
• 元素 JSON 记录（assets/omni-process-element-dr-extract.json、assets/omni-process-element-set-values.json 模板）——每个操作步骤对应的 OmniProcessElement 记录，已配置 PropertySetConfig
• 验证报告——涵盖 6 个类别、总分 110 分，并给出部署／审核／阻止阈值结果
• 部署检查清单——确认前置 DataRaptor 已激活、IP 已激活，且调用它的 OmniScript 或 FlexCard 能够调用该 IP

---

备注

API：最新版本（请查看当前 Salesforce 发行说明；撰写本文时为 66.0）| 模式：严格（警告会阻止操作）| 评分：若得分 < 67，则阻止部署

依赖项（可选）：deploying-metadata、building-omnistudio-datamapper、analyzing-omnistudio-dependencies

以编程方式创建 IP：使用 REST API（sf api request rest --method POST --body @file.json）。必填字段：Name、Type、SubType、Language、VersionNumber、IsIntegrationProcedure=true。然后为每个操作步骤创建 OmniProcessElement 子记录（JSON PropertySetConfig 也通过 REST API 设置）。创建所有元素后，将 IsActive=true 以激活。

---

参考文件索引

文件	读取时机
assets/omni-process-ip.json	第 3 阶段 — 生成：通过 REST API 创建集成过程时，将其用作 OmniProcess 记录模板
assets/omni-process-element-dr-extract.json	第 3 阶段 — 生成：将其用作 DataRaptor Extract Action 元素模板；其他 DR 操作类型可据此调整
assets/omni-process-element-set-values.json	第 3 阶段 — 生成：将其用作变量赋值步骤的 Set Values 元素模板
assets/scoring-report-format.txt	第 3 阶段 — 验证：呈现 110 分验证报告时，将其用作输出布局模板
references/best-practices.md	第 2 至 5 阶段 — 设计模式：元素组合、错误处理、缓存、并行执行和安全指南
references/element-types.md	第 2 阶段 — 元素选择：配置任何元素类型的 PropertySetConfig 之前先阅读
scripts/cli-commands.sh	第 1 和第 4 阶段 — CLI 查询及部署／检索命令；请替换 <Name> 和 <org> 占位符后再使用