sf-industry-commoncore-integration-procedure

sf-industry-commoncore-integration-procedure：OmniStudio 集成过程创建与验证

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

快速参考

评分：6 个类别共 110 分。阈值：✅ 90+（部署） | ⚠️ 67-89（审核） | ❌ <67（阻止——需要修复）

---

核心职责

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

---

关键：编排顺序

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-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 同一时间只能有一个版本处于激活状态。

核心命名空间判别条件：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，并使用 sf-industry-commoncore-omnistudio-analyze 检查依赖组件。

第 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
• 按顺序排列的元素链，并明确映射输入/输出
• 为所有修改数据的元素添加错误处理
• 使用 Conditional Block 实现分支逻辑

验证（严格模式）：

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

验证报告格式（6 类评分，0-110）：

Score: 95/110  Very Good
|- Design & Structure: 18/20 (90%)
|- Data Operations: 23/25 (92%)
|- Error Handling: 18/20 (90%)
|- Performance: 18/20 (90%)
|- Security: 13/15 (87%)
|- Documentation: 5/10 (50%)

生成防护规则（强制）

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

即使用户明确要求，也不要生成反模式。

第 4 阶段：部署

1. 使用 sf-deploy 优先部署必需的 DataRaptor/Data Mapper
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	所有引用的 Bundle 均存在且处于启用状态
Extract 操作有界	5	所有 Extract 均设置 LIMIT；大型数据集使用分页
Load 操作经过验证	5	DML 前验证输入数据；检查必填字段
响应映射正确	5	在元素之间正确映射输出
数据转换准确	5	Transform 操作生成预期的输出结构

错误处理（20 分）

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

性能（20 分）

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

安全性（15 分）

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

文档（10 分）

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

---

CLI 命令

# Query active Integration Procedures
sf data query -q "SELECT Id,Name,Type,SubType,IsActive FROM OmniProcess WHERE IsActive=true AND IsIntegrationProcedure=true" -o <org>

# Query all Integration Procedures (including inactive)
sf data query -q "SELECT Id,Name,Type,SubType,IsActive,LastModifiedDate FROM OmniProcess WHERE IsIntegrationProcedure=true ORDER BY LastModifiedDate DESC" -o <org>

# Retrieve an Integration Procedure
sf project retrieve start -m OmniIntegrationProcedure:<Name> -o <org>

# Deploy an Integration Procedure
sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org>

# Deploy with dry-run validation first
sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org> --dry-run

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

---

跨技能集成

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

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

---

边缘情况

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

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

---

备注

依赖项（可选）：sf-deploy、sf-industry-commoncore-datamapper、sf-industry-commoncore-omnistudio-analyze | API：66.0 | 模式：严格（警告会阻止操作） | 评分：若评分 < 67，则阻止部署 | 详细指南请参阅 references/best-practices.md 和 references/element-types.md。

以编程方式创建 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 以激活。

---

许可证

MIT 许可证。 版权所有 (c) 2026 David Ryan (weytani)