omnistudio-omniscript-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

omnistudio-omniscript-generate: OmniStudio OmniScript Creation and Validation

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

Expert OmniStudio OmniScript builder for declarative, step-based guided digital experiences. OmniScripts are the OmniStudio analog of Screen Flows: multi-step, interactive processes that collect input, orchestrate server-side logic (Integration Procedures, DataRaptors), and present results to the user — all without code.

专业的OmniStudio OmniScript构建工具，用于声明式、基于步骤的引导式数字体验。OmniScript相当于OmniStudio中的Screen Flows：无需代码即可实现多步骤交互式流程，收集输入、编排服务器端逻辑（Integration Procedures、DataRaptors）并向用户展示结果。

Quick Reference

快速参考

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

评分规则：6大类别总计120分。阈值标准：✅ 90分及以上（可部署）| ⚠️ 67-89分（需审核）| ❌ 低于67分（需修复，禁止部署）

Scope

适用范围

In scope: Creating OmniScripts from requirements, element selection and PropertySetConfig design, dependency analysis (Integration Procedures, DataRaptors), data flow tracing, 120-point validation scoring, deployment and activation
Out of scope: Building FlexCards (use
```
omnistudio-flexcard-generate
```
), creating Integration Procedures directly (use
```
omnistudio-integration-procedure-generate
```
), mapping full dependency trees (use
```
omnistudio-dependencies-analyze
```
), deploying metadata to org (use
```
platform-metadata-deploy
```
)

包含场景：根据需求创建OmniScript、元素选择与PropertySetConfig设计、依赖分析（Integration Procedures、DataRaptors）、数据流追踪、120分验证评分、部署与激活
排除场景：构建FlexCards（使用
```
omnistudio-flexcard-generate
```
）、直接创建Integration Procedures（使用
```
omnistudio-integration-procedure-generate
```
）、映射完整依赖树（使用
```
omnistudio-dependencies-analyze
```
）、将元数据部署到组织（使用
```
platform-metadata-deploy
```
）

Required Inputs

必填输入项

Gather these before building:

Input	Description	Default
Type	Process category (e.g., `ServiceRequest` , `Enrollment` )	None — required
SubType	Specific variation (e.g., `NewCase` , `UpdateAddress` )	None — required
Language	Locale for the OmniScript	`English`
Purpose	Business process this OmniScript guides	None — required
Target org	Org alias for deployment	Current default org
Data sources	Objects/APIs to query or update	Identify from requirements

构建前需收集以下信息：

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

Core Responsibilities

核心职责

OmniScript Generation: Create well-structured OmniScripts from requirements, selecting appropriate element types for each step
Element Design: Configure PropertySetConfig JSON for each element with correct data binding, validation, and conditional logic
Dependency Analysis: Map all references to Integration Procedures, DataRaptors, and embedded OmniScripts before deployment
Data Flow Analysis: Trace data through the OmniScript JSON structure — from prefill through user input to final save actions

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

CRITICAL: Orchestration Order

重要提示：编排顺序

omnistudio-dependencies-analyze → omnistudio-datamapper-generate → omnistudio-integration-procedure-generate → omnistudio-omniscript-generate → omnistudio-flexcard-generate (you are here: omnistudio-omniscript-generate)

OmniScripts consume Integration Procedures and DataRaptors. Build those FIRST. FlexCards may launch OmniScripts — build FlexCards AFTER. Use omnistudio-dependencies-analyze to map the full dependency tree before starting.

OmniScript依赖Integration Procedures和DataRaptors，需优先构建这些组件。FlexCards可能会启动OmniScript，需在OmniScript之后构建。开始前使用omnistudio-dependencies-analyze映射完整的依赖树。

Key Insights

关键要点

Insight	Details
Type/SubType/Language triplet	Uniquely identifies an OmniScript. All three values are required and form the composite key. Example: Type= `ServiceRequest` , SubType= `NewCase` , Language= `English`
PropertySetConfig	JSON blob containing all element configuration — layout, data binding, validation rules, conditional visibility. This is where the real logic lives
Core namespace	OmniProcess with `IsIntegrationProcedure = false` (equivalently `OmniProcessType='OmniScript'` ). Elements are child OmniProcessElement records
Element hierarchy	Elements use Level/Order fields for tree structure. Level 0 = Steps, Level 1+ = elements within steps. Order determines sequence within a level
Version management	Multiple versions can exist; only one can be active per Type/SubType/Language triplet. Activate via the `IsActive` field
Data JSON	OmniScripts pass a single JSON data structure through all steps. Elements read from and write to this shared JSON via merge field syntax

要点	详情
Type/SubType/Language三元组	唯一标识一个OmniScript。三个值均为必填项，共同构成复合键。示例：Type= `ServiceRequest` ，SubType= `NewCase` ，Language= `English`
PropertySetConfig	包含所有元素配置的JSON对象——布局、数据绑定、验证规则、条件可见性。核心逻辑均在此处定义
核心命名空间	OmniProcess的 `IsIntegrationProcedure = false` （等效于 `OmniProcessType='OmniScript'` ）。元素为OmniProcessElement子记录
元素层级	元素使用Level/Order字段构建树形结构。Level 0 = 步骤，Level 1+ = 步骤内的元素。Order字段决定同层级内的顺序
版本管理	可存在多个版本，但每个Type/SubType/Language三元组仅能有一个激活版本。通过 `IsActive` 字段激活
数据JSON	OmniScript在所有步骤中传递单个JSON数据结构。元素通过合并字段语法读取和写入该共享JSON

Workflow Design (5-Phase Pattern)

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

Phase 1: Requirements Gathering

阶段1：需求收集

Before building, evaluate alternatives: OmniScripts are best for complex, multi-step guided processes. For simple single-screen data entry, consider Screen Flows. For data display without interaction, consider FlexCards.

Ask the user to gather:

Type: The process category (e.g.,
```
ServiceRequest
```
,
```
Enrollment
```
,
```
ClaimSubmission
```
)
SubType: The specific variation (e.g.,
```
NewCase
```
,
```
UpdateAddress
```
,
```
FileAppeal
```
)
Language: Typically
```
English
```
unless multi-language support is required
Purpose: What business process this OmniScript guides the user through
Target org: Org alias for deployment
Data sources: Which objects/APIs need to be queried or updated

Then: Check existing OmniScripts to avoid duplication, identify reusable Integration Procedures or DataRaptors, and map the dependency chain.

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

向用户收集以下信息：

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

后续操作：检查现有OmniScript避免重复，识别可复用的Integration Procedures或DataRaptors，并映射依赖链。

Phase 2: Design & Element Selection

阶段2：设计与元素选择

Design each step and select element types appropriate to the interaction pattern.

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

Container Elements

容器元素

Element Type	Purpose	Key Config
Step	Top-level container for a group of UI elements; each Step is a page in the wizard	`chartLabel` , `knowledgeOptions` , `show` (conditional visibility)
Conditional Block	Show/hide a group of elements based on conditions	`conditionType` , `show` expression
Loop Block	Iterate over a data list and render elements for each item	`loopData` (JSON path to array)
Edit Block	Inline editing container for tabular data	`editFields` , `dataSource`

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

Input Elements

输入元素

Element Type	Purpose	Key Config
Text	Single-line text input	`label` , `placeholder` , `pattern` (regex validation)
Text Area	Multi-line text input	`label` , `maxLength` , `rows`
Number	Numeric input with optional formatting	`label` , `min` , `max` , `step` , `format`
Date	Date picker	`label` , `dateFormat` , `minDate` , `maxDate`
Date/Time	Date and time picker	`label` , `dateFormat` , `timeFormat`
Checkbox	Boolean toggle	`label` , `defaultValue`
Radio	Radio button group for single selection	`label` , `options` (static or data-driven)
Select	Dropdown selection	`label` , `options` , `optionSource` (static/data)
Multi-select	Multiple item selection	`label` , `options` , `maxSelections`
Type Ahead	Search/autocomplete input	`label` , `dataSource` , `searchField` , `minCharacters`
Signature	Signature capture pad	`label` , `penColor` , `backgroundColor`
File	File upload	`label` , `maxFileSize` , `allowedExtensions`
Currency	Currency input with locale formatting	`label` , `currencyCode` , `min` , `max`
Email	Email input with format validation	`label` , `placeholder`
Telephone	Phone number input with masking	`label` , `mask` , `placeholder`
URL	URL input with format validation	`label` , `placeholder`
Password	Masked text input	`label` , `minLength`
Range	Slider input	`label` , `min` , `max` , `step`
Time	Time picker	`label` , `timeFormat`

元素类型	用途	关键配置
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`

Display Elements

显示元素

Element Type	Purpose	Key Config
Text Block	Static content display (HTML supported)	`textContent` , `HTMLTemplateId`
Headline	Section heading	`text` , `level` (h1-h6)
Aggregate	Calculated summary display	`aggregateExpression` , `format`
Disclosure	Expandable/collapsible content	`label` , `defaultExpanded`
Image	Image display	`imageURL` , `altText`
Chart	Data visualization	`chartType` , `dataSource`

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

Action Elements

动作元素

Element Type	Purpose	Key Config
DataRaptor Extract Action	Pull data from Salesforce	`bundle` , `inputMap` , `outputMap`
DataRaptor Load Action	Push data to Salesforce	`bundle` , `inputMap`
Integration Procedure Action	Call server-side Integration Procedure	`ipMethod` (Type_SubType), `inputMap` , `outputMap` , `remoteOptions`
Remote Action	Call Apex @RemoteAction or REST	`remoteClass` , `remoteMethod` , `inputMap`
Navigate Action	Page navigation or redirection	`targetType` , `targetId` , `URL`
DocuSign Envelope Action	Trigger DocuSign envelope	`templateId` , `recipientMap`
Email Action	Send email	`emailTemplateId` , `recipientMap`

元素类型	用途	关键配置
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`

Logic Elements

逻辑元素

Element Type	Purpose	Key Config
Set Values	Variable assignment and data transformation	`elementValueMap` (key-value pairs)
Validation	Input validation rules with custom messages	`validationFormula` , `errorMessage`
Formula	Calculate values using formula expressions	`expression` , `dataType`
Submit Action	Final submission of collected data	`postMessage` , `preTransformBundle` , `postTransformBundle`

元素类型	用途	关键配置
Set Values	变量赋值与数据转换	`elementValueMap` （键值对）
Validation	带自定义提示的输入验证规则	`validationFormula` 、 `errorMessage`
Formula	使用公式表达式计算值	`expression` 、 `dataType`
Submit Action	收集数据的最终提交	`postMessage` 、 `preTransformBundle` 、 `postTransformBundle`

Phase 3: Generation & Validation

阶段3：生成与验证

Run

scripts/check-duplicate-omniscript.sh <Type> <SubType> <Language> <org>

to verify no duplicate Type/SubType/Language exists.

Build the OmniScript:

Create the OmniProcess record with Type, SubType, Language, and OmniProcessType='OmniScript'
Create OmniProcessElement child records for each Step (Level=0)
Create OmniProcessElement child records for each element within Steps (Level=1+, ordered by Order field)
Configure PropertySetConfig JSON for each element
Wire action elements to their Integration Procedures / DataRaptors

Validation (STRICT MODE):

BLOCK: Missing Type/SubType/Language, circular OmniScript embedding, broken IP/DataRaptor references, missing required PropertySetConfig fields
WARN: Steps with no elements, input elements without validation, missing error handling on actions, unused data paths, deeply nested elements (>4 levels)

Validation Report Format (6-Category Scoring 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%)

运行

scripts/check-duplicate-omniscript.sh <Type> <SubType> <Language> <org>

验证是否存在重复的Type/SubType/Language组合。

构建OmniScript：

创建OmniProcess记录，设置Type、SubType、Language，且OmniProcessType='OmniScript'
为每个Step创建OmniProcessElement子记录（Level=0）
为Step内的每个元素创建OmniProcessElement子记录（Level=1+，按Order字段排序）
为每个元素配置PropertySetConfig JSON
将动作元素关联到对应的Integration Procedures / DataRaptors

验证（严格模式）：

禁止部署：缺失Type/SubType/Language、OmniScript循环嵌入、IP/DataRaptor引用失效、PropertySetConfig必填字段缺失
警告：无元素的Step、无验证的输入元素、动作元素缺失错误处理、未使用的数据路径、嵌套过深的元素（超过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%)

Phase 4: Deployment

阶段4：部署

Prerequisites: Verify org auth (
```
sf org display -o <org>
```
). Confirm all referenced DataRaptors and Integration Procedures are active in the target org.
Deploy all dependencies first: DataRaptors, Integration Procedures, referenced OmniScripts.
Run
```
scripts/deploy-omniscript.sh <Name> <Type> <SubType> <org>
```
— this deploys the OmniScript and verifies activation. If deployment fails, the script outputs recovery instructions (deactivate and delete the partial record, then retry).
Activate the OmniScript version after successful deployment if not auto-activated.

前置条件：验证组织授权（
```
sf org display -o <org>
```
）。确认所有引用的DataRaptors和Integration Procedures在目标组织中已激活。
优先部署所有依赖项：DataRaptors、Integration Procedures、引用的OmniScripts。
运行
```
scripts/deploy-omniscript.sh <Name> <Type> <SubType> <org>
```
—— 该脚本将部署OmniScript并验证激活状态。若部署失败，脚本会输出恢复说明（停用并删除部分记录，然后重试）。
若未自动激活，部署成功后激活OmniScript版本。

Phase 5: Testing

阶段5：测试

Walk through all paths with various data scenarios:

Happy path: Complete all steps with valid data, verify submission
Validation testing: Submit invalid data at each input, verify error messages
Conditional testing: Exercise all conditional blocks and verify show/hide logic
Data prefill: Verify DataRaptor Extract Actions populate elements correctly
Save for later: Test resume functionality if enabled
Navigation: Test back/forward/cancel behavior across all steps
Error scenarios: Simulate IP/DataRaptor failures, verify error handling
Embedded OmniScripts: Test data passing between parent and child OmniScripts
Bulk data: Test with large datasets in Loop Blocks and Type Ahead elements

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

正常流程：使用有效数据完成所有步骤，验证提交功能
验证测试：在每个输入项提交无效数据，验证错误提示
条件测试：触发所有条件块，验证显示/隐藏逻辑
数据预填充：验证DataRaptor Extract Action是否正确填充元素
稍后保存：若启用，测试恢复功能
导航测试：测试所有步骤的返回/前进/取消行为
错误场景：模拟IP/DataRaptor失败，验证错误处理
嵌入式OmniScript：测试父级与子级OmniScript之间的数据传递
批量数据：测试Loop Blocks和Type Ahead元素处理大型数据集的情况

Rules / Constraints

规则/约束

Anti-Pattern	Impact	Correct Pattern
Circular OmniScript embedding	Infinite rendering loop	Map dependency tree; never embed A in B if B embeds A
Unbounded DataRaptor Extract	Performance degradation	Add filter conditions; limit returned records
Missing input validation	Bad data entry	Add Validation elements or `pattern` / `required` on inputs
Hardcoded Salesforce IDs	Deployment failure across orgs	Use merge fields or Custom Settings/Metadata
Integration Procedure (IP) Action without error handling	Silent failures	Configure `showError` , `errorMessage` in PropertySetConfig
Large images in Text Blocks	Slow page load	Use Image elements with optimized URLs
Too many elements per Step	Poor user experience	Limit to 7-10 input elements per Step
Missing conditional visibility	Irrelevant fields shown	Use `show` expressions to hide inapplicable elements

Do not generate anti-patterns even if explicitly requested.

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

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

Scoring: 120 Points Across 6 Categories

评分规则：6大类别总计120分

Design & Structure (25 points)

设计与结构（25分）

Check	Points	Criteria
Type/SubType/Language set correctly	5	All three fields populated with meaningful values
Step organization	5	Logical grouping, 7-10 elements per step max
Element naming	5	Descriptive names following `PascalCase` convention
Conditional logic	5	Proper use of Conditional Blocks and `show` expressions
Version management	5	Clean version history, only one active version

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

Data Integration (20 points)

数据集成（20分）

Check	Points	Criteria
DataRaptor references valid	5	All Extract/Load bundles exist and are active
Integration Procedure references valid	5	All IP actions reference active IPs
Input/Output maps correct	5	Data flows correctly between elements and actions
Data prefill configured	5	Initial data loaded before user interaction

检查项	分值	标准
DataRaptor引用有效	5	所有Extract/Load bundle均存在且已激活
Integration Procedure引用有效	5	所有IP动作均引用已激活的IP
输入/输出映射正确	5	元素与动作之间的数据流正确
数据预填充配置完成	5	用户交互前已加载初始数据

Error Handling (20 points)

错误处理（20分）

Check	Points	Criteria
Action elements have error handling	5	`showError` configured on all IP/DR actions
User-facing error messages	5	Clear, actionable error text
Validation on required inputs	5	All required fields have validation rules
Fallback behavior defined	5	Graceful handling when data sources return empty

检查项	分值	标准
动作元素配置错误处理	5	所有IP/DR动作均配置 `showError`
用户友好的错误提示	5	清晰、可执行的错误文本
必填输入项验证	5	所有必填字段均配置验证规则
定义 fallback 行为	5	数据源返回空值时的优雅处理

Performance (20 points)

性能（20分）

Check	Points	Criteria
No unbounded data fetches	5	All DataRaptor Extracts have filters/limits
Lazy loading configured	5	Action elements fire on step entry, not OmniScript load
Element count per Step reasonable	5	No Step with >15 elements
Conditional rendering used	5	Elements hidden when not applicable (not just invisible)

检查项	分值	标准
无无限制的数据获取	5	所有DataRaptor Extract均配置过滤/限制条件
配置懒加载	5	动作元素在Step进入时触发，而非OmniScript加载时
单个Step元素数量合理	5	无Step包含超过15个元素
使用条件渲染	5	不适用的元素被隐藏（而非仅不可见）

User Experience (20 points)

用户体验（20分）

Check	Points	Criteria
Logical step flow	5	Steps follow natural task progression
Input labels and help text	5	All inputs have clear labels and contextual help
Navigation controls	5	Back, Next, Cancel, Save for Later configured appropriately
Responsive layout	5	Elements configured for mobile and desktop breakpoints

检查项	分值	标准
步骤流逻辑合理	5	步骤遵循自然任务流程
输入标签与帮助文本	5	所有输入项均有清晰的标签和上下文帮助
导航控件配置合理	5	返回、下一步、取消、稍后保存等控件配置得当
响应式布局	5	元素适配移动端和桌面端断点

Security (15 points)

安全性（15分）

Check	Points	Criteria
No sensitive data in client-side JSON	5	Passwords, SSNs, tokens kept server-side
IP actions use server-side processing	5	Sensitive logic in Integration Procedures, not client OmniScript
Field-level access respected	5	Data access matches user profile/permission set

检查项	分值	标准
客户端JSON无敏感数据	5	密码、社保号、令牌等数据保留在服务器端
IP动作使用服务器端处理	5	敏感逻辑放在Integration Procedures中，而非客户端OmniScript
遵守字段级访问权限	5	数据访问与用户配置文件/权限集匹配

CLI Commands

CLI命令

See

scripts/cli-reference.sh

for the full command reference. Common commands:

bash

undefined

完整命令参考请查看

scripts/cli-reference.sh

。常用命令：

bash

undefined

List active OmniScripts

列出已激活的OmniScript

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

查询特定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

检查OmniScript版本

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>

---

---

Cross-Skill Integration

跨技能集成

From Skill	To omnistudio-omniscript-generate	When
omnistudio-dependencies-analyze	-> omnistudio-omniscript-generate	"Analyze dependencies before building OmniScript"
omnistudio-datamapper-generate	-> omnistudio-omniscript-generate	"DataRaptor ready, build the OmniScript that uses it"
omnistudio-integration-procedure-generate	-> omnistudio-omniscript-generate	"IP ready, wire it into the OmniScript action"

From omnistudio-omniscript-generate	To Skill	When
omnistudio-omniscript-generate	-> omnistudio-flexcard-generate	"Build FlexCard that launches this OmniScript"
omnistudio-omniscript-generate	-> platform-metadata-deploy	"Deploy OmniScript to target org"
omnistudio-omniscript-generate	-> omnistudio-dependencies-analyze	"Map full dependency tree before deployment"
omnistudio-omniscript-generate	-> omnistudio-integration-procedure-generate	"Need a new IP for this OmniScript action"
omnistudio-omniscript-generate	-> omnistudio-datamapper-generate	"Need a DataRaptor for data prefill"

来源技能	目标技能：omnistudio-omniscript-generate	触发时机
omnistudio-dependencies-analyze	-> omnistudio-omniscript-generate	"构建OmniScript前分析依赖关系"
omnistudio-datamapper-generate	-> omnistudio-omniscript-generate	"DataRaptor已就绪，构建使用它的OmniScript"
omnistudio-integration-procedure-generate	-> omnistudio-omniscript-generate	"IP已就绪，将其关联到OmniScript动作"

来源技能：omnistudio-omniscript-generate	目标技能	触发时机
omnistudio-omniscript-generate	-> omnistudio-flexcard-generate	"构建启动该OmniScript的FlexCard"
omnistudio-omniscript-generate	-> platform-metadata-deploy	"将OmniScript部署到目标组织"
omnistudio-omniscript-generate	-> omnistudio-dependencies-analyze	"部署前映射完整依赖树"
omnistudio-omniscript-generate	-> omnistudio-integration-procedure-generate	"为该OmniScript动作创建新IP"
omnistudio-omniscript-generate	-> omnistudio-datamapper-generate	"为数据预填充创建DataRaptor"

Gotchas

常见问题

Issue	Resolution
Multi-language OmniScript	Create separate versions per Language with shared Type/SubType; use translation workbench for labels
Embedded OmniScript data passing	Map parent data JSON keys to child OmniScript input via `prefillJSON` ; test data round-trip
Large Loop Block datasets	Paginate or limit DataRaptor results; consider server-side filtering in Integration Procedure (IP)
OmniScript in FlexCard flyout	Ensure FlexCard passes required context data; test flyout sizing
Community/Experience Cloud deployment	Verify OmniScript component is available in Experience Builder; check guest user permissions
Save & Resume (Save for Later)	Configure `saveNameTemplate` , `saveExpireInDays` ; test resume with partial data
Versioning conflicts	Deactivate old version before activating new; never have two active versions for same Type/SubType/Language triplet
Custom LWC in OmniScript	Register LWC as OmniScript-compatible; follow `omniscript-lwc` namespace conventions
Namespaced orgs	If deploying into a managed OmniStudio package org, prefix bundle names and API names with the appropriate namespace (e.g., `omnistudio__` )
`OmniProcessType` cannot be set on create	`OmniProcessType` is computed from `IsIntegrationProcedure` (false for OmniScripts); do not set it directly

For common runtime troubleshooting (element not rendering, data not prefilling, IP action failing silently), see

references/best-practices.md

Section 8.

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

常见运行时故障排查（元素不渲染、数据不预填充、IP动作静默失败）请查看

references/best-practices.md

第8节。

Notes

注意事项

API: 66.0 | Mode: Strict (warnings block) | Scoring: Block deployment if score < 67

Required upstream skills:

omnistudio-datamapper-generate

omnistudio-integration-procedure-generate

Optional skills:

platform-metadata-deploy

omnistudio-flexcard-generate

omnistudio-dependencies-analyze

Creating OmniScripts programmatically: Use REST API (

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

). Required fields:

Name

Type

SubType

Language

VersionNumber

. OmniScripts default to

IsIntegrationProcedure=false

— do NOT set

OmniProcessType

directly (it is computed). The

sf data create record --values

flag cannot handle JSON textarea fields like

PropertySetConfig

. Create child

OmniProcessElement

records via REST API for each Step and element.

API版本：66.0 | 模式：严格（警告会阻止部署）| 评分规则：评分低于67分时禁止部署

必填上游技能：

omnistudio-datamapper-generate

、

omnistudio-integration-procedure-generate

可选技能：

platform-metadata-deploy

、

omnistudio-flexcard-generate

、

omnistudio-dependencies-analyze

以编程方式创建OmniScript：使用REST API（

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

）。必填字段：

Name

、

Type

、

SubType

、

Language

、

VersionNumber

。OmniScript默认

IsIntegrationProcedure=false

—— 请勿直接设置

OmniProcessType

（它是计算得出的）。

sf data create record --values

标志无法处理

PropertySetConfig

这类JSON文本区域字段。需通过REST API为每个Step和元素创建子

OmniProcessElement

记录。

Output Expectations

输出预期

Deliverables produced by this skill:

OmniScript JSON (
```
assets/omni-process-omniscript.json
```
template) — OmniProcess record ready for REST API creation
Step element JSON (
```
assets/omni-process-element-step.json
```
template) — OmniProcessElement record for each Step (Level=0)
Element JSON (
```
assets/omni-process-element-text-block.json
```
and similar) — OmniProcessElement records for child elements (Level=1+)
Validation report — 120-point score across 6 categories with pass/warn/block threshold result

本技能生成的交付物：

OmniScript JSON（
```
assets/omni-process-omniscript.json
```
模板）—— 可通过REST API创建的OmniProcess记录
Step元素JSON（
```
assets/omni-process-element-step.json
```
模板）—— 每个Step的OmniProcessElement记录（Level=0）
元素JSON（
```
assets/omni-process-element-text-block.json
```
及类似模板）—— 子元素的OmniProcessElement记录（Level=1+）
验证报告—— 6大类别120分评分结果，包含通过/警告/禁止阈值

Reference File Index

参考文件索引

File	When to read
`references/element-types.md`	Phase 2 — Element selection: read before configuring PropertySetConfig for any element type
`references/best-practices.md`	Phase 2-5 — Design patterns: read for step design, data prefill, validation, navigation, performance, and troubleshooting guidance
`assets/omni-process-omniscript.json`	Phase 3 — Generation: use as the OmniProcess record template when building the OmniScript via REST API
`assets/omni-process-element-step.json`	Phase 3 — Generation: use as the Step (Level=0) OmniProcessElement record template
`assets/omni-process-element-text-block.json`	Phase 3 — Generation: use as the Text Block element template; adapt for other display element types
`scripts/check-duplicate-omniscript.sh`	Phase 3 — Run before creating a new OmniScript to verify no duplicate Type/SubType/Language exists
`scripts/deploy-omniscript.sh`	Phase 4 — Run to deploy OmniScript and verify activation; includes prerequisite checks and error recovery
`scripts/cli-reference.sh`	Any phase — Full CLI command reference for querying, retrieving, deploying, and verifying OmniScripts

文件	阅读时机
`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 —— 生成：作为Step（Level=0）OmniProcessElement记录模板使用
`assets/omni-process-element-text-block.json`	阶段3 —— 生成：作为Text Block元素模板使用；可适配其他显示元素类型
`scripts/check-duplicate-omniscript.sh`	阶段3 —— 创建新OmniScript前运行，验证是否存在重复的Type/SubType/Language组合
`scripts/deploy-omniscript.sh`	阶段4 —— 运行以部署OmniScript并验证激活状态；包含前置检查和错误恢复逻辑
`scripts/cli-reference.sh`	任意阶段 —— 查询、检索、部署和验证OmniScript的完整CLI命令参考