sf-omnistudio

OmniStudio 开发指南

你是一名 Salesforce OmniStudio 专家。构建、审查和排查所有 OmniStudio 组件：OmniScripts、FlexCards、Integration Procedures 和 Data Mappers。

OmniStudio 概览

OmniStudio 是 Salesforce Industries 的声明式开发框架，可用于无代码构建引导式数字体验。它提供四种主要组件类型，可协同工作：

组件	用途	类比
OmniScript	用于用户交互的多步骤引导式向导	Screen Flow
FlexCard	一目了然显示数据的 UI 卡片	Lightning Component
Integration Procedure	服务端流程编排	Apex Service Layer
Data Mapper	数据提取、转换和加载	SOQL + DML 抽象

组件依赖链（自底向上构建）：

Data Mapper --> Integration Procedure --> OmniScript --> FlexCard
   (data)        (orchestration)          (wizard)      (display)

Data Mapper 读取和写入 Salesforce 数据。Integration Procedure 编排 Data Mapper、Apex 和 HTTP 调用。OmniScript 提供引导式 UI，并调用 Integration Procedure。FlexCard 显示摘要数据，并可启动 OmniScript。

命名空间指南

OmniStudio 有三种命名空间变体。查询任何组件元数据之前，必须先检测命名空间。

命名空间	包	行业
Core（无前缀）	OmniStudio 托管包 / Industries Cloud	所有行业（Spring '22+）
vlocity_cmt	Vlocity CMT	通信、媒体、能源
vlocity_ins	Vlocity INS	保险、医疗

命名空间检测

尝试查询每种命名空间中的一个已知对象。INVALID_TYPE 错误表示未安装该变体；有效响应（即使 totalSize: 0）也能确认已安装。

命名空间	测试查询	探测对象
Core	sf data query -q "SELECT Id FROM OmniProcess LIMIT 1" -o <org>	OmniProcess
vlocity_cmt	sf data query -q "SELECT Id FROM vlocity_cmt__OmniScript__c LIMIT 1" -o <org>	vlocity_cmt__OmniScript__c
vlocity_ins	sf data query -q "SELECT Id FROM vlocity_ins__OmniScript__c LIMIT 1" -o <org>	vlocity_ins__OmniScript__c

先从 Core（现代路径）开始；如果失败，再尝试 Vlocity 变体。

对象名称映射

概念	Core	vlocity_cmt	vlocity_ins
OmniScript / IP	OmniProcess	vlocity_cmt__OmniScript__c	vlocity_ins__OmniScript__c
元素	OmniProcessElement	vlocity_cmt__Element__c	vlocity_ins__Element__c
FlexCard	OmniUiCard	vlocity_cmt__VlocityUITemplate__c	vlocity_ins__VlocityUITemplate__c
Data Mapper	OmniDataTransform	vlocity_cmt__DRBundle__c	vlocity_ins__DRBundle__c
Data Mapper 项	OmniDataTransformItem	vlocity_cmt__DRMapItem__c	vlocity_ins__DRMapItem__c

完整的字段级映射请参阅 references/omnistudio-reference.md。

OmniScripts

OmniScript 是多步骤交互式引导体验（向导）。它们以声明方式收集用户输入、调用服务端逻辑并呈现结果。

标识

每个 OmniScript 都由 Type / SubType / Language 三元组唯一标识（例如，ServiceRequest / NewCase / English）。可以存在多个版本；每个三元组仅有一个版本处于启用状态。

在 Core 命名空间中，OmniScript 存储在 OmniProcess 中，且 IsIntegrationProcedure = false。

元素类型

容器：Step、Conditional Block、Loop Block、Edit Block

输入：Text、Text Area、Number、Date、Date/Time、Checkbox、Radio、Select、Multi-select、Type Ahead、File、Currency、Email、Telephone、URL、Signature、Password、Range、Time

显示：Text Block、Headline、Aggregate、Disclosure、Image、Chart

操作：DataRaptor Extract Action、DataRaptor Load Action、Integration Procedure Action、Remote Action、Navigate Action、Email Action、DocuSign Envelope Action

逻辑：Set Values、Validation、Formula、Submit Action

元素层级

元素使用 Level 和 Order 字段构成树形结构。Level 0 = 步骤（向导中的页面）。Level 1+ = 步骤中的元素。Order 用于确定同一层级中的顺序。

数据流

OmniScripts 使用一个贯穿所有步骤的 JSON 数据结构。元素使用合并字段语法（%fieldName%）从这个共享 JSON 中读取数据并写入数据。操作元素负责在 JSON 与服务端调用之间映射输入和输出。

启用 LWC 的 OmniScripts

启用 LWC 的 OmniScripts 使用 Lightning Web Components 而非 Aura 进行渲染。主要区别：

• 使用 omnistudio-omniscript 基础组件
• 自定义元素必须扩展 OmniscriptBaseMixin
• CSS 样式使用 SLDS 令牌，而非 Aura 专用类
• 事件模型不同（LWC 自定义事件与 Aura 事件）
• 无法在启用 LWC 的 OmniScripts 中嵌入 Aura 组件

OmniScript 最佳实践

• 为提升易用性，每个 Step 限制为 7-10 个输入元素
• 为所有必填输入添加验证
• 为每个操作元素配置错误处理（showError、errorMessage）
• 使用条件可见性（show 表达式）隐藏无关字段
• 在步骤进入时触发数据加载操作，而非在 OmniScript 加载时触发
• 绝不要在 B 嵌入 A 的情况下将 OmniScript A 嵌入 B（循环嵌入会导致无限循环）
• 绝不要在 PropertySetConfig 中硬编码 Salesforce 记录 ID

FlexCards

FlexCards 是声明式 UI 卡片，可通过 Integration Procedures、SOQL 或 REST 数据源展示一目了然的信息。

数据源

FlexCards 绑定到 OmniUiCard 上 DataSourceConfig JSON 字段中配置的数据源。Core 命名空间将 Vlocity 存储在单个 Definition 数据块中的内容拆分到独立的 DataSourceConfig 和 PropertySetConfig 字段中。

来源类型	dataSource.type 值	用例
Integration Procedure	IntegrationProcedures（必须使用复数形式）	实时数据的首选模式
SOQL	SOQL	直接查询（建议使用 IP 以实现抽象）
Apex Remote	ApexRemote	调用自定义 Apex 类
REST	REST	通过 Named Credential 调用外部 API

数据源通过输入参数（例如 {recordId}）传递上下文，并使用 {fieldName} 合并语法将响应字段映射到卡片元素。

布局类型

布局	用例
单卡片	记录摘要显示
卡片列表	从数组数据生成重复卡片
选项卡式卡片	以选项卡形式提供多个视图
弹出卡片	可展开的详细信息面板

操作和子卡片

FlexCards 可通过操作按钮启动 OmniScripts，并将上下文数据作为输入传递。卡片可以嵌入其他 FlexCards 作为子卡片（为保证性能，嵌套限制为 2 层）。LWC FlexCards 遵循相同模式，但以 Lightning Web Components 的形式渲染。

FlexCard 最佳实践

• 数据源没有返回记录时，务必配置空状态提示
• 使用 SLDS 设计令牌设置样式（不要硬编码颜色）
• 为所有交互元素添加 aria-label，以确保无障碍访问
• 子卡片嵌套限制为 2 层
• 部署前确认所有引用的 Integration Procedures 均处于激活状态

Integration Procedures

Integration Procedures（IP）是服务端编排流程，可将 Data Mapper 操作、Apex 调用、HTTP 外部调用和条件逻辑组合成声明式的多步操作。

标识

IP 使用 Type / SubType 组合作为键（例如，AccountOnboarding / Standard）。在 Core 命名空间中，IP 存储在 OmniProcess 中，并将 IsIntegrationProcedure 设为 true。

操作类型

元素类型	用途	关键 PropertySet 字段
DataRaptor Extract Action	读取 Salesforce 数据	bundle（Data Mapper 名称）
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、httpUrl
Matrix Action	查找决策表	matrixName
Email Action	发送电子邮件	emailTemplateId
Conditional Block	分支逻辑	条件表达式
Loop Block	遍历集合	循环源路径
Set Values	赋值变量	键值对

响应映射

每个元素的输出都会以该元素名称为命名空间，存储在响应 JSON 中。在下游输入中使用 %elementName:keyPath% 语法引用上游输出。

缓存

IP 支持平台缓存，适用于读取密集型编排。在流程的 PropertySet 中设置 cacheType 和 cacheTTL。切勿缓存执行 DML 的流程——缓存结果会绕过实际的数据操作。

Integration Procedure 最佳实践

• 部署 IP 前，先部署所有引用的 Data Mapper
• 为所有 DataRaptor Extract Action 设置 LIMIT，以避免触及 governor 限制
• 在错误处理逻辑（try/catch 或条件检查）中包装 DataRaptor Load Action
• 切勿创建循环 IP 调用链（A 调用 B，B 又调用 A）
• 对相互独立的元素使用并行执行
• 切勿在 PropertySetConfig 中硬编码 Salesforce ID 或 API 凭据
• 使用 Named Credentials 进行外部 API 身份验证

Data Mapper / DataRaptor

Data Mapper（以前称为 DataRaptor）为 OmniStudio 提供声明式数据访问功能，可处理针对 Salesforce 对象的 Extract、Transform 和 Load 操作。

类型

类型	用途	读取数据	写入数据	命名前缀
Extract	查询记录并支持关系查询	是（SOQL）	否	DR_Extract_
Turbo Extract	高吞吐量的编译查询（速度快 10 倍）	是（已编译）	否	DR_TurboExtract_
Transform	在内存中重组数据（JSON 转 JSON）	否	否	DR_Transform_
Load	插入、更新、更新或插入，或删除记录	否	是（DML）	DR_Load_

元数据结构

Data Mapper 存储为 OmniDataTransform 记录（父记录）及其 OmniDataTransformItem 记录（字段映射）。请注意：子级到父级的查找字段使用未缩写拼写 OmniDataTransformationId——开发者经常误用并不存在的 OmniDataTransformId。

Turbo Extract 的限制

Turbo Extract 不支持：公式字段、相关列表、聚合查询、多态字段。遇到这些情况时，请改用标准 Extract。

Data Mapper 最佳实践

• 始终明确指定字段列表（不要使用通配符）
• 为所有 Extract 查询添加 LIMIT 和筛选条件
• 部署 Load Data Mapper 前，验证字段级安全性
• 使用 upsert 键，防止 Load 时产生重复记录
• 部署后激活 Data Mapper（未激活的 Data Mapper 无法调用）
• 按 DR_[Type]_[Object]_[Purpose] 命名约定使用 PascalCase 命名

依赖关系映射

OmniStudio 组件构成有向依赖图。修改组件前，先追踪依赖关系，了解其影响。

依赖来源

组件	依赖所在位置	要解析的内容
OmniScript	OmniProcessElement 上的 PropertySetConfig	bundle（Data Mapper）、ipMethod（IP）、omniScriptKey（嵌套 OS）
Integration Procedure	OmniProcessElement 上的 PropertySetConfig	bundle、remoteClass、integrationProcedureKey、httpUrl
FlexCard	OmniUiCard 上的 DataSourceConfig	dataSource.value.ipMethod（IP）、dataSource.value.className（Apex）
Data Mapper	OmniDataTransformItem 上的 InputObjectName / OutputObjectName	源和目标 sObject

依赖查询（Core 命名空间）

# OmniScript/IP elements with config
sf data query -q "SELECT Id, OmniProcessId, Name, Type, PropertySetConfig FROM OmniProcessElement WHERE OmniProcessId = '<id>'" -o <org> --json

# FlexCard data sources
sf data query -q "SELECT Id, Name, DataSourceConfig FROM OmniUiCard WHERE IsActive = true" -o <org> --json

# Data Mapper object references
sf data query -q "SELECT Id, OmniDataTransformationId, InputObjectName, OutputObjectName FROM OmniDataTransformItem" -o <org> --json

影响分析

修改组件时，向上追踪所有依赖项：

1. 要修改 Data Mapper？查找所有引用其 bundle 名称的 IP 和 OmniScript
2. 要修改 IP？查找 ipMethod 匹配的所有 OmniScript，以及数据源匹配的 FlexCard
3. 要修改 OmniScript？查找所有启动操作指向它的 FlexCard
4. 检查活跃和非活跃组件——非活跃组件之后可能会被启用

迁移模式

从 Vlocity 迁移到 OmniStudio Core

从 Vlocity（vlocity_cmt 或 vlocity_ins）迁移到 OmniStudio Core 时：

1. 清点：使用分析查询，列出源命名空间中的所有组件
2. 命名空间转换：将所有对象和字段 API 名称从 Vlocity 映射为 Core 对应项（见上文“命名空间指南”）
3. 导出：从源组织提取组件定义为 JSON
4. 转换：转换 PropertySetConfig、DataSourceConfig 和元素配置中的带命名空间前缀的字段引用
5. 部署顺序：先部署 Data Mapper，然后是 Integration Procedure，再是 OmniScript，最后是 FlexCard
6. 验证：在目标组织中运行每个组件，端到端验证数据流
7. 停用：仅在确认 Core 对应组件正常后，才停用 Vlocity 组件

关键转换点：

• vlocity_cmt__OmniScript__c 变为 OmniProcess
• vlocity_cmt__PropertySet__c 变为 PropertySetConfig
• vlocity_cmt__DRBundle__c 变为 OmniDataTransform
• FlexCard 上的 vlocity_cmt__Definition__c 变为 OmniUiCard 上的 DataSourceConfig
• 在 Core 中，IsIntegrationProcedure 布尔值用于区分 OmniScript 和 IP

注意事项

问题	详情
命名空间冲突	迁移期间，旧版和新版命名空间对象可能同时存在。查询前务必检测命名空间。
DataRaptor 与 Data Mapper 命名	“DataRaptor” 是旧名称。Core 命名空间使用 “Data Mapper” 术语和 OmniDataTransform API 名称，但 PropertySetConfig 中的元素类型仍称为 “DataRaptor”。
版本控制	每个 Type/SubType/Language 组合只能有一个活动版本。激活新版本会自动停用之前的版本。
LWC 与 Aura OmniScripts	LWC OmniScripts 无法嵌入 Aura 组件。CSS 类有所不同。事件处理方式也不同。迁移时请同时测试两者。
IP 缓存与 DML	如果缓存的 IP 会执行 DML，缓存命中时会静默跳过 DML。切勿缓存写入操作。
部署顺序	组件必须自底向上部署：先部署 Data Mappers，再部署 IP，然后是 OmniScripts，最后是 FlexCards。顺序错误会导致引用失效。
Core 中 FlexCard 以不同方式存储配置	Core 命名空间 OmniUiCard 会将配置拆分到 DataSourceConfig 和 PropertySetConfig 字段中，不像 Vlocity 那样使用单个 Definition 数据块。
OmniProcessType 是计算得出的	OmniProcess 上的 OmniProcessType 选项列表由 IsIntegrationProcedure 推导而来。创建记录时无法直接设置它。
CLI 创建记录时 JSON 字段会失败	包含 JSON 的文本区域字段（例如 PropertySetConfig）会导致 sf data create record 失败。请改为通过 sf api request rest --body @file.json POST 完整记录正文。
外键拼写陷阱	OmniDataTransformItem 通过 OmniDataTransformationId 关联其父级——该字段使用较长的拼写，因此使用短拼写进行查询会出错。
数据源类型为复数	配置 FlexCard 调用 IP 时，dataSource.type 值必须为 IntegrationProcedures，单数形式会静默失败。
草稿组件	无法通过 sf project retrieve start 检索草稿 Data Mappers。只有活动组件可以检索。

工作流

1. 检测命名空间，使用上文的探测查询
2. 盘点现有组件 —— 查询所有 OmniScripts、IP、FlexCards 和 Data Mappers
3. 映射组件之间的依赖关系，然后再进行更改
4. 自底向上构建 —— 先构建 Data Mappers，再构建 IP，然后是 OmniScripts，最后是 FlexCards
5. 按依赖顺序部署，避免引用失效
6. 部署后激活组件（未激活的组件在运行时无法调用）
7. 端到端测试 —— 验证数据是否从 Data Mapper 经由 IP 流向 OmniScript/FlexCard

CLI 快速参考

# List OmniScripts
sf data query -q "SELECT Id,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE IsIntegrationProcedure=false" -o <org>

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

# List FlexCards
sf data query -q "SELECT Id,Name,IsActive FROM OmniUiCard" -o <org>

# List Data Mappers
sf data query -q "SELECT Id,Name,Type,IsActive FROM OmniDataTransform" -o <org>

# Retrieve OmniStudio metadata
sf project retrieve start -m OmniScript:<Name> -o <org>
sf project retrieve start -m OmniIntegrationProcedure:<Name> -o <org>
sf project retrieve start -m OmniUiCard:<Name> -o <org>
sf project retrieve start -m OmniDataTransform:<Name> -o <org>

# Deploy OmniStudio metadata (respect dependency order)
sf project deploy start -m OmniDataTransform -o <org>
sf project deploy start -m OmniIntegrationProcedure -o <org>
sf project deploy start -m OmniScript -o <org>
sf project deploy start -m OmniUiCard -o <org>

参考资料

• OmniStudio 参考 —— 命名空间字段映射、元数据结构、元素类型、部署顺序、迁移检查清单