omnistudio-integration-procedure-generate

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

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

范围

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

---

所需输入

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

---

快速参考

评分：6 个类别，共 110 分。阈值：[PASS] 90 分以上（部署）| [REVIEW] 67–89 分（审核）| [BLOCK] 少于 67 分（阻止——必须修复）

---

核心职责

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

---

关键：编排顺序

omnistudio-dependencies-analyze -> omnistudio-datamapper-generate -> omnistudio-integration-procedure-generate -> omnistudio-omniscript-generate -> omnistudio-flexcard-generate（你现在所在的位置：omnistudio-integration-procedure-generate）

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 在 OmniProcess 表中同时存储 Integration Procedure 和 OmniScript。使用 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）
• 部署目标 org 的别名

然后：通过 CLI 查询检查现有 IP（见下文 CLI 命令），确定可复用的 DataRaptor/Data Mapper，并使用 omnistudio-dependencies-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
• 按顺序排列元素链，并明确映射输入/输出
• 为所有修改数据的元素处理错误
• 使用条件块实现分支逻辑

验证（严格模式）：

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

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

生成防护规则（必须遵守）

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

即使收到明确请求，也不得生成反模式。

第 4 阶段：部署

1. 首先使用 platform-metadata-deploy 部署前置 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 Procedure 前，请先阅读 scripts/cli-commands.sh——其中包含所有 SOQL 查询以及可供调整使用的 sf project 部署/检索命令。

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

---

跨技能集成

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

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

---

边缘情况

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

调试：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 可以正常运行

---

备注

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

依赖项（可选）：platform-metadata-deploy、omnistudio-datamapper-generate、omnistudio-dependencies-analyze

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

---

参考文件索引

文件	何时阅读
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> 占位符替换为实际值

---

交付前检查清单

• Data Mapper 已创建并部署，然后 IP 才引用它
• 通过 Data API 创建时已设置 IsIntegrationProcedure = true
• OmniScript/FlexCard 调用 IP 前，IP 已激活