building-omnistudio-omniscript

building-omnistudio-omniscript：OmniStudio OmniScript 创建与验证

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

快速参考

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

---

范围

• 范围内：根据需求创建 OmniScript，选择元素并设计 PropertySetConfig，分析依赖项（Integration Procedure、DataRaptor），追踪数据流，按 120 分制验证评分，以及部署和激活
• 范围外：构建 FlexCard（使用 building-omnistudio-flexcard），直接创建 Integration Procedure（使用 building-omnistudio-integration-procedure），映射完整依赖树（使用 analyzing-omnistudio-dependencies），将元数据部署到组织（使用 deploying-metadata）

---

必需输入

构建前收集以下信息：

输入	说明	默认值
Type	流程类别（例如，ServiceRequest、Enrollment）	无——必填
SubType	具体变体（例如，NewCase、UpdateAddress）	无——必填
Language	OmniScript 的区域设置	English
Purpose	此 OmniScript 引导的业务流程	无——必填
Target org	部署所用的组织别名	当前默认组织
Data sources	要查询或更新的对象/API	根据需求确定

---

核心职责

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

---

关键：编排顺序

analyzing-omnistudio-dependencies → building-omnistudio-datamapper → building-omnistudio-integration-procedure → building-omnistudio-omniscript → building-omnistudio-flexcard（当前位置：building-omnistudio-omniscript）

OmniScript 会调用 Integration Procedure 和 DataRaptor。请先构建它们。FlexCard 可能会启动 OmniScript，因此应在之后构建 FlexCard。开始前，使用 analyzing-omnistudio-dependencies 映射完整的依赖树。

---

关键要点

要点	详情
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 字段激活
Data JSON	OmniScript 会在所有步骤中传递同一个 JSON 数据结构。元素通过合并字段语法读取和写入此共享 JSON

---

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

阶段 1：需求收集

开始构建前，请评估替代方案：OmniScripts 最适合复杂的多步骤引导流程。对于简单的单屏数据录入，请考虑使用 Screen Flows。对于无需交互的数据展示，请考虑使用 FlexCards。

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

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

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

阶段 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 操作	从 Salesforce 提取数据	bundle、inputMap、outputMap
DataRaptor Load 操作	将数据推送到 Salesforce	bundle、inputMap
Integration Procedure 操作	调用服务器端 Integration Procedure	ipMethod（Type_SubType）、inputMap、outputMap、remoteOptions
远程操作	调用 Apex @RemoteAction 或 REST	remoteClass、remoteMethod、inputMap
导航操作	页面导航或重定向	targetType、targetId、URL
DocuSign 信封操作	触发 DocuSign 信封	templateId、recipientMap
电子邮件操作	发送电子邮件	emailTemplateId、recipientMap

逻辑元素

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

阶段 3：生成与验证

运行 scripts/check-duplicate-omniscript.sh <Type> <SubType> <Language> <org>，确认不存在重复的 Type/SubType/Language。

构建 OmniScript：

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

验证（严格模式）：

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

验证报告格式（6 类评分，0-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. 先决条件：验证组织身份验证（sf org display -o <org>）。确认所有引用的 DataRaptor 和 Integration Procedure 在目标组织中均处于活动状态。
2. 首先部署所有依赖项：DataRaptor、Integration Procedure、引用的 OmniScript。
3. 运行 scripts/deploy-omniscript.sh <Name> <Type> <SubType> <org> — 此操作会部署 OmniScript 并验证其激活状态。如果部署失败，脚本会输出恢复说明（停用并删除不完整记录，然后重试）。
4. 成功部署后，如果未自动激活，则激活 OmniScript 版本。

阶段 5：测试

使用各种数据场景检查所有路径：

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

---

规则 / 约束

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

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

---

评分：6 个类别，共 120 分

设计与结构（25 分）

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

数据集成（20 分）

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

错误处理（20 分）

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

性能（20 分）

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

用户体验（20 分）

检查项	分数	标准
Step 流程合理	5	Step 按照自然的任务顺序排列
输入标签和帮助文本	5	所有输入项均有清晰的标签和上下文帮助
导航控件	5	根据需要配置 Back、Next、Cancel、Save for Later
响应式布局	5	为移动设备和桌面设备的断点配置元素

安全性（15 分）

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

---

CLI 命令

完整的命令参考请参见 scripts/cli-reference.sh。常用命令：

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

# Query elements for a specific OmniScript
sf data query -q "SELECT Id,Name,ElementType,Level,Order FROM OmniProcessElement WHERE OmniProcessId='<id>' ORDER BY Level,Order LIMIT 200" -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 LIMIT 10" -o <org>

---

跨技能集成

来源技能	到构建 OmniStudio OmniScript	适用情形
analyzing-omnistudio-dependencies	-> building-omnistudio-omniscript	“构建 OmniScript 前先分析依赖项”
building-omnistudio-datamapper	-> building-omnistudio-omniscript	“DataRaptor 已就绪，构建使用它的 OmniScript”
building-omnistudio-integration-procedure	-> building-omnistudio-omniscript	“IP 已就绪，将它接入 OmniScript 操作”

来源技能	到技能	适用情形
building-omnistudio-omniscript	-> building-omnistudio-flexcard	“构建用于启动此 OmniScript 的 FlexCard”
building-omnistudio-omniscript	-> deploying-metadata	“将 OmniScript 部署到目标组织”
building-omnistudio-omniscript	-> analyzing-omnistudio-dependencies	“部署前映射完整的依赖关系树”
building-omnistudio-omniscript	-> building-omnistudio-integration-procedure	“需要为此 OmniScript 操作新建 IP”
building-omnistudio-omniscript	-> building-omnistudio-datamapper	“需要用于数据预填充的 DataRaptor”

---

注意事项

问题	解决方法
多语言 OmniScript	为每种语言创建单独版本，并共享 Type/SubType；使用翻译工作台处理标签
嵌入式 OmniScript 数据传递	将父级数据 JSON 键映射到子级 OmniScript 输入中的 prefillJSON；测试数据往返传递
大型 Loop Block 数据集	对 DataRaptor 结果进行分页或限制；考虑在 Integration Procedure (IP) 中进行服务器端筛选
FlexCard 弹出层中的 OmniScript	确保 FlexCard 传递所需的上下文数据；测试弹出层尺寸
Community/Experience Cloud 部署	确认 Experience Builder 中有 OmniScript 组件；检查访客用户权限
保存并恢复（稍后保存）	配置 saveNameTemplate、saveExpireInDays；使用部分数据测试恢复
版本冲突	激活新版本前停用旧版本；同一 Type/SubType/Language 组合绝不能有两个激活版本
OmniScript 中的自定义 LWC	将 LWC 注册为 OmniScript 兼容；遵循 omniscript-lwc 命名空间约定
带命名空间的组织	如果部署到受管理的 OmniStudio 包组织中，请为捆绑包名称和 API 名称添加相应的命名空间前缀（例如 omnistudio__）
创建时无法设置 OmniProcessType	OmniProcessType 根据 IsIntegrationProcedure 计算得出（OmniScripts 中为 false）；不要直接设置

常见运行时问题排查（元素未渲染、数据未预填充、IP 操作静默失败），请参阅 references/best-practices.md 第 8 节。

---

备注

API：66.0 | 模式：严格（警告会阻止操作） | 评分：如果评分 < 67，则阻止部署

必需的上游技能：building-omnistudio-datamapper、building-omnistudio-integration-procedure

可选技能：deploying-metadata、building-omnistudio-flexcard、analyzing-omnistudio-dependencies

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

---

输出要求

此技能生成的交付物：

• OmniScript JSON（assets/omni-process-omniscript.json 模板）——可通过 REST API 创建的 OmniProcess 记录
• 步骤元素 JSON（assets/omni-process-element-step.json 模板）——每个步骤对应的 OmniProcessElement 记录（Level=0）
• 元素 JSON（assets/omni-process-element-text-block.json 等）——子元素对应的 OmniProcessElement 记录（Level=1+）
• 验证报告——涵盖 6 个类别、满分 120 分，并给出通过／警告／阻止阈值结果

---

参考文件索引

文件	阅读时机
references/element-types.md	阶段 2——元素选择：为任何元素类型配置 PropertySetConfig 前阅读
references/best-practices.md	阶段 2-5——设计模式：阅读以了解步骤设计、数据预填、验证、导航、性能和故障排除指南
assets/omni-process-omniscript.json	阶段 3——生成：通过 REST API 构建 OmniScript 时，将其用作 OmniProcess 记录模板
assets/omni-process-element-step.json	阶段 3——生成：将其用作步骤（Level=0）OmniProcessElement 记录模板
assets/omni-process-element-text-block.json	阶段 3——生成：将其用作文本块元素模板；其他显示元素类型可据此调整
scripts/check-duplicate-omniscript.sh	阶段 3——运行此脚本，再创建 OmniScript，以确认不存在相同 Type/SubType/Language 的记录
scripts/deploy-omniscript.sh	阶段 4——运行此脚本以部署 OmniScript 并验证其激活状态；包含前置检查和错误恢复
scripts/cli-reference.sh	任意阶段——查询、检索、部署和验证 OmniScript 的完整 CLI 命令参考