sf-integration-procedure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sf-integration-procedure: OmniStudio Integration Procedure Creation and Validation

sf-integration-procedure：OmniStudio Integration Procedure创建与验证

Expert OmniStudio Integration Procedure (IP) builder with deep knowledge of server-side process orchestration. Create production-ready IPs that combine DataRaptor/Data Mapper actions, Apex Remote Actions, HTTP callouts, conditional logic, and nested procedure calls into declarative multi-step operations.

精通服务器端流程编排的专业OmniStudio Integration Procedure（IP）构建工具。可创建生产级IP，将DataRaptor/Data Mapper操作、Apex Remote Actions、HTTP调用、条件逻辑和嵌套流程调用整合为声明式多步骤操作。

Quick Reference

快速参考

Scoring: 110 points across 6 categories. Thresholds: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block - fix required)

评分体系：6大类别共110分。阈值标准：✅ 90分及以上（可部署） | ⚠️ 67-89分（需审核） | ❌ 低于67分（阻止部署，需修复）

Core Responsibilities

核心职责

IP Generation: Create well-structured Integration Procedures from requirements, selecting correct element types and wiring inputs/outputs
Element Composition: Assemble DataRaptor actions, Remote Actions, HTTP callouts, conditional blocks, loops, and nested IP calls into coherent orchestrations
Dependency Analysis: Validate that referenced DataRaptors, Apex classes, and nested IPs exist and are active before deployment
Error Handling: Enforce try/catch patterns, conditional rollback, and response validation across all data-modifying steps

IP生成：根据需求创建结构清晰的Integration Procedure，选择正确的元素类型并配置输入/输出映射
元素组合：将DataRaptor操作、Remote Actions、HTTP调用、条件块、循环和嵌套IP调用组装为连贯的编排流程
依赖分析：部署前验证引用的DataRaptor、Apex类和嵌套IP是否存在且处于激活状态
错误处理：在所有数据修改步骤中强制实施try/catch模式、条件回滚和响应验证

CRITICAL: Orchestration Order

关键：编排顺序

sf-omnistudio-analyze -> sf-datamapper -> sf-integration-procedure -> sf-omniscript -> sf-flexcard (you are here: sf-integration-procedure)

Data Mappers referenced by the IP must exist FIRST. Build and deploy DataRaptors/Data Mappers before the IP that calls them. The IP must be active before any OmniScript or FlexCard can invoke it.

sf-omnistudio-analyze -> sf-datamapper -> sf-integration-procedure -> sf-omniscript -> sf-flexcard（当前处于sf-integration-procedure环节）

IP引用的Data Mapper必须提前创建。在调用它们的IP构建和部署之前，需先构建并部署DataRaptor/Data Mapper。IP必须处于激活状态，才能被OmniScript或FlexCard调用。

Key Insights

核心要点

Insight	Details
Chaining	IPs call other IPs via Integration Procedure Action elements. Output of one step feeds input of the next via response mapping. Design data flow linearly where possible.
Response Mapping	Each element's output is namespaced under its element name in the response JSON. Use `%elementName:keyPath%` syntax to reference upstream outputs in downstream inputs.
Caching	IPs support platform cache for read-heavy orchestrations. Set `cacheType` and `cacheTTL` in the procedure's PropertySet. Avoid caching procedures that perform DML.
Versioning	Type/SubType pairs uniquely identify an IP. Use SubType for versioning (e.g., `Type=AccountOnboarding` , `SubType=v2` ). Only one version can be active at a time per Type/SubType.

Core Namespace Discriminator: OmniStudio Core stores both Integration Procedures and OmniScripts in the

OmniProcess

table. Use

IsIntegrationProcedure = true

OmniProcessType = 'Integration Procedure'

to filter IPs. Without a filter, queries return mixed results.

CRITICAL — Creating IPs via Data API: When creating OmniProcess records, set
IsIntegrationProcedure = true
to make the record an Integration Procedure. The
OmniProcessType
picklist is computed from this boolean and cannot be set directly. Also,
Name
is a required field on
OmniProcess
(not documented in standard OmniStudio docs). Use
sf api request rest --method POST --body @file.json
for creation — the
sf data create record --values
flag cannot handle JSON textarea fields like
PropertySetConfig
.

要点	详情
链式调用	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文本区域字段。

Workflow Design (5-Phase Pattern)

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

Phase 1: Requirements Gathering

阶段1：需求收集

Before building, evaluate alternatives: Sometimes a single DataRaptor, an Apex service, or a Flow is the better choice. IPs are optimal when you need declarative multi-step orchestration with branching, error handling, and mixed data sources.

Ask the user to gather:

Purpose and business process being orchestrated
Target objects and data sources (Salesforce objects, external APIs, or both)
Type/SubType naming (e.g.,
```
Type=OrderProcessing
```
,
```
SubType=Standard
```
)
Target org alias for deployment

Then: Check existing IPs via CLI query (see CLI Commands below), identify reusable DataRaptors/Data Mappers, and review dependent components with sf-omnistudio-analyze.

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

请用户收集以下信息：

编排的业务流程及目的
目标对象和数据源（Salesforce对象、外部API或两者兼有）
Type/SubType命名规则（例如：
```
Type=OrderProcessing
```
，
```
SubType=Standard
```
）
部署的目标组织别名

随后：通过CLI查询检查现有IP（见下方CLI命令），识别可复用的DataRaptor/Data Mapper，并使用sf-omnistudio-analyze审核依赖组件。

Phase 2: Design & Element Selection

阶段2：设计与元素选择

Element Type	Use Case	PropertySet Key
DataRaptor Extract Action	Read Salesforce data	`bundle`
DataRaptor Load Action	Write Salesforce data	`bundle`
DataRaptor Transform Action	Data shaping/mapping	`bundle`
Remote Action	Call Apex class method	`remoteClass` , `remoteMethod`
Integration Procedure Action	Call nested IP	`ipMethod` (format: `Type_SubType` )
HTTP Action	External API callout	`path` , `method`
Conditional Block	Branching logic	--
Loop Block	Iterate over collections	--
Set Values	Assign variables/constants	--

Naming Convention:

[Type]_[SubType]

using PascalCase. Element names within the IP should describe their action clearly (e.g.,

GetAccountDetails

ValidateInput

CreateOrderRecord

Data Flow: Design the element chain so each step's output feeds naturally into the next step's input. Map outputs explicitly rather than relying on implicit namespace merging.

元素类型	使用场景	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	分配变量/常量	--

命名规范：使用帕斯卡命名法

[Type]_[SubType]

。IP内的元素名称应清晰描述其操作（例如：

GetAccountDetails

、

ValidateInput

、

CreateOrderRecord

）。

数据流：设计元素链时，确保每个步骤的输出自然流入下一步的输入。显式映射输出，而非依赖隐式命名空间合并。

Phase 3: Generation & Validation

阶段3：生成与验证

Build the IP definition with:

Correct Type/SubType assignment
Ordered element chain with explicit input/output mappings
Error handling on all data-modifying elements
Conditional blocks for branching logic

Validation (STRICT MODE):

BLOCK: Missing Type/SubType, circular IP calls, DML without error handling, references to nonexistent DataRaptors/Apex classes
WARN: Unbounded extracts without LIMIT, missing caching on read-only IPs, hardcoded IDs in PropertySetConfig, unused elements, missing element descriptions

Validation Report Format (6-Category Scoring 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定义时需包含：

正确的Type/SubType分配
有序的元素链及显式输入/输出映射
所有数据修改元素的错误处理
用于分支逻辑的条件块

验证（严格模式）：

阻止部署：缺少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%)

Generation Guardrails (MANDATORY)

生成规则（强制遵守）

Anti-Pattern	Impact	Correct Pattern
Circular IP calls (A calls B calls A)	Infinite loop / stack overflow	Map dependency graph; no cycles allowed
DML without error handling	Silent data corruption	Wrap DataRaptor Load in try/catch or conditional error check
Unbounded DataRaptor Extract	Governor limits / timeout	Set LIMIT on extracts; paginate large datasets
Hardcoded Salesforce IDs in PropertySetConfig	Deployment failure across orgs	Use input variables, Custom Settings, or Custom Metadata
Sequential calls that could be parallel	Unnecessary latency	Group independent elements; no serial dependency needed
Missing response validation	Downstream null reference errors	Check element response before passing to next step

DO NOT generate anti-patterns even if explicitly requested.

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

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

Phase 4: Deployment

阶段4：部署

Deploy prerequisite DataRaptors/Data Mappers FIRST using sf-deploy

Deploy the Integration Procedure:

sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org>

Activate the IP in the target org (set
```
IsActive=true
```
)
Verify activation via CLI query

首先使用sf-deploy部署前置依赖的DataRaptor/Data Mapper

部署Integration Procedure：

sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org>

在目标组织中激活IP（设置
```
IsActive=true
```
）
通过CLI查询验证激活状态

Phase 5: Testing

阶段5：测试

Test each element individually before testing the full chain:

Unit: Invoke each DataRaptor independently, verify Apex Remote Action responses
Integration: Run the full IP with representative input JSON, verify output structure
Error paths: Test with invalid input, missing records, API failures to verify error handling
Bulk: Test with collection inputs to verify loop and batch behavior
End-to-end: Invoke the IP from its consumer (OmniScript, FlexCard, or API) and verify the full round-trip

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

单元测试：独立调用每个DataRaptor，验证Apex Remote Action响应
集成测试：使用代表性输入JSON运行完整IP，验证输出结构
错误路径测试：使用无效输入、缺失记录、API失败等场景测试错误处理逻辑
批量测试：使用集合输入测试循环和批处理行为
端到端测试：从消费者（OmniScript、FlexCard或API）调用IP，验证完整往返流程

Scoring Breakdown

评分细则

110 points across 6 categories:

6大类别共110分：

Design & Structure (20 points)

设计与结构（20分）

Criterion	Points	Description
Type/SubType naming	5	Follows convention, descriptive, versioned appropriately
Element naming	5	Clear, action-oriented names on all elements
Data flow clarity	5	Linear or well-documented branching; explicit input/output mapping
Element ordering	5	Logical execution sequence; no unnecessary dependencies

评分标准	分值	描述
Type/SubType命名	5	遵循规范、描述性强、版本管理合理
元素命名	5	所有元素名称清晰、面向操作
数据流清晰度	5	线性或文档完善的分支结构；显式输入/输出映射
元素排序	5	逻辑执行顺序；无不必要的依赖

Data Operations (25 points)

数据操作（25分）

Criterion	Points	Description
DataRaptor references valid	5	All referenced bundles exist and are active
Extract operations bounded	5	LIMIT set on all extracts; pagination for large datasets
Load operations validated	5	Input data validated before DML; required fields checked
Response mapping correct	5	Outputs correctly mapped between elements
Data transformation accuracy	5	Transform actions produce expected output structure

评分标准	分值	描述
DataRaptor引用有效性	5	所有引用的bundle存在且处于激活状态
提取操作受限	5	所有提取操作设置LIMIT；大型数据集分页
加载操作验证	5	DML前验证输入数据；检查必填字段
响应映射正确性	5	元素间输出映射正确
数据转换准确性	5	转换操作生成预期的输出结构

Error Handling (20 points)

错误处理（20分）

Criterion	Points	Description
DML error handling	8	All DataRaptor Load actions have error handling
HTTP error handling	4	All HTTP actions check status codes and handle failures
Remote Action error handling	4	Apex exceptions caught and surfaced
Rollback strategy	4	Multi-step DML has conditional rollback or compensating actions

评分标准	分值	描述
DML错误处理	8	所有DataRaptor Load操作均有错误处理
HTTP错误处理	4	所有HTTP操作检查状态码并处理失败场景
Remote Action错误处理	4	捕获Apex异常并反馈
回滚策略	4	多步骤DML具备条件回滚或补偿操作

Performance (20 points)

性能（20分）

Criterion	Points	Description
No unbounded queries	5	All extracts have reasonable LIMIT values
Caching applied	5	Read-only procedures use platform cache where appropriate
Parallel execution	5	Independent elements not serialized unnecessarily
No redundant calls	5	Same data not fetched multiple times across elements

评分标准	分值	描述
无无限制查询	5	所有提取操作设置合理的LIMIT值
启用缓存	5	只读流程在合适场景下使用平台缓存
并行执行	5	独立元素未被不必要地串行化
无冗余调用	5	同一数据未在多个元素中重复获取

Security (15 points)

安全性（15分）

Criterion	Points	Description
No hardcoded IDs	5	IDs passed as input variables or from metadata
No hardcoded credentials	5	API keys/tokens use Named Credentials or Custom Settings
Input validation	5	User-supplied input sanitized before use in queries or DML

评分标准	分值	描述
无硬编码ID	5	ID通过输入变量或元数据传递
无硬编码凭证	5	API密钥/令牌使用命名凭证或自定义设置
输入验证	5	用户提供的输入在查询或DML使用前进行清理

Documentation (10 points)

文档（10分）

Criterion	Points	Description
Procedure description	3	Clear description of purpose and business context
Element descriptions	4	Each element has a description explaining its role
Input/output documentation	3	Expected input JSON and output JSON structure documented

评分标准	分值	描述
流程描述	3	清晰描述目的和业务背景
元素描述	4	每个元素都有说明其作用的描述
输入/输出文档	3	记录预期的输入JSON和输出JSON结构

CLI Commands

CLI命令

bash

undefined

bash

undefined

Query active Integration Procedures

查询激活的Integration Procedure

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)

查询所有Integration Procedure（包括未激活的）

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

检索Integration Procedure

sf project retrieve start -m OmniIntegrationProcedure:<Name> -o <org>

Deploy an Integration Procedure

部署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


**Core Namespace Note**: The `IsIntegrationProcedure=true` filter is REQUIRED (or equivalently `OmniProcessType='Integration Procedure'`). OmniScript and Integration Procedure records share the `OmniProcess` sObject. Without this filter, queries return both types and produce misleading results.

---

sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org> --dry-run


**核心命名空间提示**：必须使用`IsIntegrationProcedure=true`筛选条件（或等效的`OmniProcessType='Integration Procedure'`）。OmniScript和Integration Procedure记录共享`OmniProcess`对象。如果不添加此筛选条件，查询结果会包含两种类型的记录，产生误导性结果。

---

Cross-Skill Integration

跨技能集成

From Skill	To sf-integration-procedure	When
sf-omnistudio-analyze	-> sf-integration-procedure	"Analyze dependencies before building IP"
sf-datamapper	-> sf-integration-procedure	"DataRaptor/Data Mapper is ready, wire it into IP"
sf-apex	-> sf-integration-procedure	"Apex Remote Action class deployed, configure in IP"

From sf-integration-procedure	To Skill	When
sf-integration-procedure	-> sf-deploy	"Deploy IP to target org"
sf-integration-procedure	-> sf-omniscript	"IP is active, build OmniScript that calls it"
sf-integration-procedure	-> sf-flexcard	"IP is active, build FlexCard data source"
sf-integration-procedure	-> sf-omnistudio-analyze	"Verify IP dependency graph before deployment"

来源技能	目标sf-integration-procedure	触发时机
sf-omnistudio-analyze	-> sf-integration-procedure	"构建IP前分析依赖关系"
sf-datamapper	-> sf-integration-procedure	"DataRaptor/Data Mapper已准备就绪，将其接入IP"
sf-apex	-> sf-integration-procedure	"Apex Remote Action类已部署，在IP中配置"

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

Edge Cases

边缘场景

Scenario	Solution
IP calls itself (direct recursion)	Block at design time; circular dependency check is mandatory
IP calls IP that calls original (indirect recursion)	Map full call graph; sf-omnistudio-analyze detects cycles
DataRaptor not yet deployed	Deploy DataRaptors first; IP deployment will fail on missing references
External API timeout	Set timeout values on HTTP Action elements; implement retry logic or graceful degradation
Large collection input to Loop Block	Set batch size; test with realistic data volumes to avoid CPU timeout
Type/SubType collision with existing IP	Query existing IPs before creating; SubType versioning avoids collisions
Mixed namespace (Vlocity vs Core)	Confirm org namespace; element property names differ between packages

Debug: IP not executing -> check IsActive flag + Type/SubType match | Elements skipped -> verify conditional block logic + input data shape | Timeout -> check DataRaptor query scope + HTTP timeout settings | Deployment failure -> verify all referenced components deployed and active

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

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

Notes

说明

Dependencies (optional): sf-deploy, sf-datamapper, sf-omnistudio-analyze | API: 66.0 | Mode: Strict (warnings block) | Scoring: Block deployment if score < 67 | See

references/best-practices.md

and

references/element-types.md

for detailed guidance.

Creating IPs programmatically: Use REST API (

sf api request rest --method POST --body @file.json

). Required fields:

Name

Type

SubType

Language

VersionNumber

IsIntegrationProcedure=true

. Then create

OmniProcessElement

child records for each action step (also via REST API for JSON PropertySetConfig). Activate by setting

IsActive=true

after all elements are created.

依赖项（可选）：sf-deploy、sf-datamapper、sf-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

子记录（同样通过REST API处理JSON格式的PropertySetConfig）。所有元素创建完成后，设置

IsActive=true

激活IP。