sf-industry-commoncore-omniscript

sf-industry-commoncore-omniscript：OmniStudio OmniScript 创建与验证

面向专家的 OmniStudio OmniScript 构建工具，用于创建声明式、分步骤的引导式数字体验。OmniScript 相当于 OmniStudio 版的 Screen Flow：它是多步骤交互式流程，可收集输入、编排服务器端逻辑（Integration Procedure、DataRaptor），并向用户呈现结果——无需编写代码。

快速参考

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

---

核心职责

1. OmniScript 生成：根据需求创建结构良好的 OmniScript，为每个步骤选择适当的元素类型
2. 元素设计：为每个元素配置 PropertySetConfig JSON，确保数据绑定、验证和条件逻辑正确
3. 依赖分析：在部署前梳理对 Integration Procedure、DataRaptor 和嵌入式 OmniScript 的所有引用
4. 数据流分析：追踪数据在 OmniScript JSON 结构中的流转——从预填充到用户输入，再到最终保存操作

---

重要：编排顺序

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-omniscript）

OmniScript 使用 Integration Procedure 和 DataRaptor。请先构建它们。FlexCard 可以启动 OmniScript，因此应在之后构建 FlexCard。开始前，使用 sf-industry-commoncore-omnistudio-analyze 梳理完整的依赖树。

---

关键要点

要点	详情
Type/SubType/Language 三元组	唯一标识一个 OmniScript。必须提供全部三个值，它们共同构成复合键。示例：Type=ServiceRequest，SubType=NewCase，Language=English
PropertySetConfig	包含所有元素配置的 JSON 数据块——布局、数据绑定、验证规则和条件可见性。真正的逻辑都在这里
Core 命名空间	OmniProcess，且 IsIntegrationProcedure = false（等效于 OmniProcessType='OmniScript'）。元素是子 OmniProcessElement 记录
元素层级	元素使用 Level/Order 字段构建树形结构。Level 0 = 步骤，Level 1+ = 步骤内的元素。Order 决定同一层级内的顺序
版本管理	可以存在多个版本；每个 Type/SubType/Language 三元组只能有一个版本处于启用状态。通过 IsActive 字段启用版本
数据 JSON	OmniScript 会在所有步骤中传递同一个 JSON 数据结构。元素通过合并字段语法读取和写入此共享 JSON

---

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

阶段 1：收集需求

构建前，先评估替代方案：OmniScript 最适合复杂的多步骤引导式流程。对于简单的单屏数据录入，可考虑 Screen Flow。对于无需交互的数据展示，可考虑 FlexCard。

询问用户，收集以下信息：

• Type：流程类别（例如，ServiceRequest、Enrollment、ClaimSubmission）
• SubType：具体变体（例如，NewCase、UpdateAddress、FileAppeal）
• Language：通常为 English，除非需要多语言支持
• Purpose：此 OmniScript 将引导用户完成的业务流程
• 目标组织：用于部署的组织别名
• 数据源：需要查询或更新的对象/API

然后：检查现有 OmniScript 以避免重复，找出可复用的 Integration Procedure 或 DataRaptor，并梳理依赖链。

阶段 2：设计与元素选择

设计每个步骤，并根据交互模式选择合适的元素类型。

容器元素

元素类型	用途	关键配置
Step	一组 UI 元素的顶层容器；每个 Step 都是向导中的一个页面	chartLabel、knowledgeOptions、show（条件可见性）
Conditional Block	根据条件显示或隐藏一组元素	conditionType、show 表达式
Loop Block	遍历数据列表，并为每个项目渲染元素	loopData（指向数组的 JSON 路径）
Edit Block	表格数据的内联编辑容器	editFields、dataSource

输入元素

元素类型	用途	关键配置
Text	单行文本输入	label、placeholder、pattern（正则表达式验证）
Text Area	多行文本输入	label、maxLength、rows
Number	可选格式化的数字输入	label、min、max、step、format
Date	日期选择器	label、dateFormat、minDate、maxDate
Date/Time	日期和时间选择器	label、dateFormat、timeFormat
Checkbox	布尔值切换	label、defaultValue
Radio	单选按钮组	label、options（静态或由数据驱动）
Select	下拉选择	label、options、optionSource（静态/数据）
Multi-select	多项选择	label、options、maxSelections
Type Ahead	搜索/自动补全输入	label、dataSource、searchField、minCharacters
Signature	签名采集板	label、penColor、backgroundColor
File	文件上传	label、maxFileSize、allowedExtensions
Currency	按区域设置格式化的货币输入	label、currencyCode、min、max
Email	带格式验证的电子邮件输入	label、placeholder
Telephone	带掩码的电话号码输入	label、mask、placeholder
URL	带格式验证的 URL 输入	label、placeholder
Password	掩码文本输入	label、minLength
Range	滑块输入	label、min、max、step
Time	时间选择器	label、timeFormat

显示元素

元素类型	用途	关键配置
Text Block	静态内容显示（支持 HTML）	textContent、HTMLTemplateId
Headline	分区标题	text、level（h1-h6）
Aggregate	计算汇总显示	aggregateExpression、format
Disclosure	可展开/折叠的内容	label、defaultExpanded
Image	图像显示	imageURL、altText
Chart	数据可视化	chartType、dataSource

操作元素

元素类型	用途	关键配置
DataRaptor Extract Action	从 Salesforce 拉取数据	bundle、inputMap、outputMap
DataRaptor Load Action	将数据推送到 Salesforce	bundle、inputMap
Integration Procedure Action	调用服务器端 Integration Procedure	ipMethod（Type_SubType）、inputMap、outputMap、remoteOptions
Remote Action	调用 Apex @RemoteAction 或 REST	remoteClass、remoteMethod、inputMap
Navigate Action	页面导航或重定向	targetType、targetId、URL
DocuSign Envelope Action	触发 DocuSign 信封	templateId、recipientMap
Email Action	发送电子邮件	emailTemplateId、recipientMap

逻辑元素

元素类型	用途	关键配置
设置值	变量赋值和数据转换	elementValueMap（键值对）
验证	使用自定义消息验证输入规则	validationFormula、errorMessage
公式	使用公式表达式计算值	expression、dataType
提交操作	提交收集到的数据	postMessage、preTransformBundle、postTransformBundle

第 3 阶段：生成与验证

# Verify no duplicate Type/SubType/Language exists
sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE Type='<Type>' AND SubType='<SubType>' AND Language='<Language>' AND OmniProcessType='OmniScript'" -o <org>

构建 OmniScript：

1. 创建 OmniProcess 记录，并设置 Type、SubType、Language 和 OmniProcessType='OmniScript'
2. 为每个步骤创建 OmniProcessElement 子记录（Level=0）
3. 为步骤中的每个元素创建 OmniProcessElement 子记录（Level=1+，按 Order 字段排序）
4. 为每个元素配置 PropertySetConfig JSON
5. 将操作元素连接到其 Integration Procedures / DataRaptors

验证（严格模式）：

• 阻止：缺少 Type/SubType/Language、OmniScript 循环嵌入、IP/DataRaptor 引用失效、缺少必需的 PropertySetConfig 字段
• 警告：步骤中没有元素、输入元素未设置验证规则、操作缺少错误处理、未使用的数据路径、元素嵌套过深（超过 4 层）

验证报告格式（6 个类别，总分 120）：

Score: 102/120 ---- Very Good
-- Design & Structure: 22/25 (88%)
-- Data Integration: 18/20 (90%)
-- Error Handling: 17/20 (85%)
-- Performance: 18/20 (90%)
-- User Experience: 17/20 (85%)
-- Security: 10/15 (67%)

第 4 阶段：部署

1. 首先部署所有依赖项：DataRaptors、Integration Procedures、引用的 OmniScripts
2. 检索或部署 OmniScript 元数据：

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

3. 部署成功后激活 OmniScript 版本
4. 验证激活状态：

   sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE Type='<Type>' AND SubType='<SubType>' AND OmniProcessType='OmniScript' AND IsActive=true" -o <org>
   

第 5 阶段：测试

使用各种数据场景遍历所有路径：

• 正常路径：使用有效数据完成所有步骤，并验证提交结果
• 验证测试：在每个输入项提交无效数据，并验证错误消息
• 条件测试：测试所有条件块，并验证显示/隐藏逻辑
• 数据预填充：验证 DataRaptor Extract Actions 是否正确填充元素
• 稍后保存：如果已启用，测试恢复功能
• 导航：测试所有步骤中的后退/前进/取消行为
• 错误场景：模拟 IP/DataRaptor 故障，并验证错误处理
• 嵌入式 OmniScripts：测试父 OmniScript 与子 OmniScript 之间的数据传递
• 批量数据：使用循环块和 Type Ahead 元素测试大型数据集

---

生成护栏（强制）

反模式	影响	正确做法
循环嵌入 OmniScript	无限渲染循环	映射依赖树；如果 B 嵌入了 A，就不要让 A 嵌入 B
无限制的 DataRaptor Extract	性能下降	添加筛选条件；限制返回的记录数
缺少输入验证	数据录入错误	添加验证元素，或在输入项上设置 pattern/required
硬编码 Salesforce ID	无法在不同组织间部署	使用合并字段或 Custom Settings/Metadata
IP Action 缺少错误处理	静默失败	在 PropertySetConfig 中配置 showError、errorMessage
文本块中包含大尺寸图片	页面加载缓慢	使用具有优化 URL 的图片元素
每个步骤中元素过多	用户体验不佳	每个步骤限制为 7-10 个输入元素
缺少条件可见性	显示不相关的字段	使用 show 表达式隐藏不适用的元素

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

---

评分：6 个类别，总计 120 分

设计与结构（25 分）

检查项	分值	标准
正确设置 Type/SubType/Language	5	三个字段均已填写有意义的值
步骤组织	5	分组合理，每个步骤最多包含 7-10 个元素
元素命名	5	使用符合 PascalCase 规范的描述性名称
条件逻辑	5	正确使用 Conditional Blocks 和 show 表达式
版本管理	5	版本历史清晰，只有一个有效版本

数据集成（20 分）

检查项	分值	标准
DataRaptor 引用有效	5	所有 Extract/Load 包均存在且处于有效状态
Integration Procedure 引用有效	5	所有 IP 操作均引用有效的 IP
输入/输出映射正确	5	数据可在元素和操作之间正确流转
已配置数据预填充	5	在用户交互前加载初始数据

错误处理（20 分）

检查项	分值	标准
操作元素具有错误处理	5	所有 IP/DR 操作均配置了 showError
面向用户的错误消息	5	错误文本清晰且可指导用户采取行动
必填输入验证	5	所有必填字段均设置了验证规则
已定义回退行为	5	数据源返回空结果时可妥善处理

性能（20 分）

检查项	分值	标准
不进行无界数据获取	5	所有 DataRaptor Extract 均设置了筛选条件/限制
已配置延迟加载	5	操作元素在进入步骤时触发，而非在 OmniScript 加载时触发
每个 Step 的元素数量合理	5	每个 Step 的元素不超过 15 个
使用条件渲染	5	不适用时隐藏元素（而非仅设为不可见）

用户体验（20 分）

检查项	分值	标准
步骤流程合理	5	步骤遵循自然的任务进度
输入标签和帮助文本	5	所有输入项均有清晰标签和相关帮助信息
导航控件	5	根据需要配置 Back、Next、Cancel、Save for Later
响应式布局	5	元素已针对移动端和桌面端断点进行配置

安全性（15 分）

检查项	分值	标准
客户端 JSON 中不包含敏感数据	5	密码、SSN、令牌保留在服务器端
IP 操作使用服务器端处理	5	敏感逻辑放在 Integration Procedures 中，而非客户端 OmniScript 中
遵循字段级访问权限	5	数据访问与用户配置文件/权限集相符

---

CLI 命令

# List active OmniScripts
sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE IsActive=true AND OmniProcessType='OmniScript'" -o <org>

# Query elements for a specific OmniScript
sf data query -q "SELECT Id,Name,ElementType,PropertySetConfig,Level,Order FROM OmniProcessElement WHERE OmniProcessId='<id>' ORDER BY Level,Order" -o <org>

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

# Deploy OmniScript metadata
sf project deploy start -m OmniScript:<Name> -o <org>

# Check OmniScript versions
sf data query -q "SELECT Id,VersionNumber,IsActive,LastModifiedDate FROM OmniProcess WHERE Type='<Type>' AND SubType='<SubType>' AND OmniProcessType='OmniScript' ORDER BY VersionNumber DESC" -o <org>

---

跨技能集成

来源技能	目标 sf-industry-commoncore-omniscript	时机
sf-industry-commoncore-omnistudio-analyze	-> sf-industry-commoncore-omniscript	“构建 OmniScript 前分析依赖项”
sf-industry-commoncore-datamapper	-> sf-industry-commoncore-omniscript	“DataRaptor 已就绪，构建使用它的 OmniScript”
sf-industry-commoncore-integration-procedure	-> sf-industry-commoncore-omniscript	“IP 已就绪，将其接入 OmniScript 操作”

来源 sf-industry-commoncore-omniscript	目标技能	时机
sf-industry-commoncore-omniscript	-> sf-industry-commoncore-flexcard	“构建用于启动此 OmniScript 的 FlexCard”
sf-industry-commoncore-omniscript	-> sf-deploy	“将 OmniScript 部署到目标组织”
sf-industry-commoncore-omniscript	-> sf-industry-commoncore-omnistudio-analyze	“部署前映射完整依赖树”
sf-industry-commoncore-omniscript	-> sf-industry-commoncore-integration-procedure	“需要为此 OmniScript 操作创建新的 IP”
sf-industry-commoncore-omniscript	-> sf-industry-commoncore-datamapper	“需要用于数据预填充的 DataRaptor”

---

边缘情况

场景	解决方案
多语言 OmniScript	为每种语言创建单独版本，并共享 Type/SubType。使用翻译工作台处理标签
嵌入式 OmniScript 数据传递	将父级数据 JSON 键映射到子级 OmniScript 输入，通过 prefillJSON 传递。测试数据往返
大型 Loop Block 数据集	对 DataRaptor 结果分页或设限。考虑在 IP 中进行服务器端筛选
FlexCard 飞出面板中的 OmniScript	确保 FlexCard 传递所需的上下文数据。测试飞出面板尺寸
Community/Experience Cloud 部署	确认 OmniScript 组件在 Experience Builder 中可用。检查访客用户权限
保存并恢复（Save for Later）	配置 saveNameTemplate、saveExpireInDays。测试使用部分数据恢复
版本冲突	激活新版本前停用旧版本。同一组三元组绝不能同时有两个激活版本
OmniScript 中的自定义 Lightning Web Components	将 LWC 注册为 OmniScript 兼容组件。遵循 omniscript-lwc 命名空间约定

调试：OmniScript 未渲染 -> 检查激活状态和元素层级 | 数据未预填 -> 验证 DataRaptor Extract 输出映射和 JSON 路径 | IP 操作失败 -> 先单独检查 IP，并验证输入映射 | 步骤未显示 -> 检查条件可见性表达式

---

备注

依赖项（必需）：sf-industry-commoncore-datamapper、sf-industry-commoncore-integration-procedure | 依赖项（可选）：sf-deploy、sf-industry-commoncore-flexcard、sf-industry-commoncore-omnistudio-analyze | API：66.0 | 模式：严格（警告会阻止操作） | 评分：如果分数 < 67，则阻止部署 | 参考文档：有关元素类型和最佳实践，请参阅 references/

以编程方式创建 OmniScripts：使用 REST API（sf api request rest --method POST --body @file.json）。必填字段：Name、Type、SubType、Language、VersionNumber。OmniScripts 默认 IsIntegrationProcedure=false（请勿设置 OmniProcessType，它是计算得出的）。sf data create record --values 标志无法处理 PropertySetConfig 等 JSON 文本区域字段。通过 REST API 为每个 Step 和元素创建子级 OmniProcessElement 记录。

---

许可证

MIT License。 版权所有 (c) 2026 David Ryan (weytani)