building-omnistudio-omniscript: OmniStudio OmniScript Creation and Validation

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.

Quick Reference

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

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 building-omnistudio-flexcard), creating Integration Procedures directly (use building-omnistudio-integration-procedure), mapping full dependency trees (use analyzing-omnistudio-dependencies), deploying metadata to org (use deploying-metadata)

Required Inputs

Gather these before building:

Core Responsibilities

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

CRITICAL: Orchestration Order

analyzing-omnistudio-dependencies → building-omnistudio-datamapper → building-omnistudio-integration-procedure → building-omnistudio-omniscript → building-omnistudio-flexcard (you are here: building-omnistudio-omniscript)

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

Key Insights

Workflow Design (5-Phase Pattern)

Phase 1: Requirements Gathering

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.

Phase 2: Design & Element Selection

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

Container Elements

Input Elements

Display Elements

Action Elements

Logic Elements

Phase 3: Generation & Validation

Run scripts/check-duplicate-omniscript.sh <Type> <SubType> <Language> <org> to verify no duplicate Type/SubType/Language exists.

Build the OmniScript:

1. Create the OmniProcess record with Type, SubType, Language, and OmniProcessType='OmniScript'
2. Create OmniProcessElement child records for each Step (Level=0)
3. Create OmniProcessElement child records for each element within Steps (Level=1+, ordered by Order field)
4. Configure PropertySetConfig JSON for each element
5. 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%)

Phase 4: Deployment

1. Prerequisites: Verify org auth (sf org display -o <org>). Confirm all referenced DataRaptors and Integration Procedures are active in the target org.
2. Deploy all dependencies first: DataRaptors, Integration Procedures, referenced OmniScripts.
3. 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).
4. Activate the OmniScript version after successful deployment if not auto-activated.

Phase 5: Testing

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

Rules / Constraints

Do not generate anti-patterns even if explicitly requested.

Scoring: 120 Points Across 6 Categories

Design & Structure (25 points)

Data Integration (20 points)

Error Handling (20 points)

Performance (20 points)

User Experience (20 points)

Security (15 points)

CLI Commands

See scripts/cli-reference.sh for the full command reference. Common commands:

# 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>

Cross-Skill Integration

Gotchas

For common runtime troubleshooting (element not rendering, data not prefilling, IP action failing silently), see references/best-practices.md Section 8.

Notes

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

Required upstream skills: building-omnistudio-datamapper, building-omnistudio-integration-procedure

Optional skills: deploying-metadata, building-omnistudio-flexcard, analyzing-omnistudio-dependencies

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.

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

Reference File Index