sf-omniscript（科幻全向文字）

sf-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)

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

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

OmniScripts consume Integration Procedures and DataRaptors. Build those FIRST. FlexCards may launch OmniScripts — build FlexCards AFTER. Use sf-omnistudio-analyze 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

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

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. Deploy all dependencies first: DataRaptors, Integration Procedures, referenced OmniScripts
2. Retrieve or deploy OmniScript metadata: sf project retrieve start -m OmniScript:<Name> -o <org> sf project deploy start -m OmniScript:<Name> -o <org>
3. Activate the OmniScript version after successful deployment
4. Verify activation: 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>

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

Generation Guardrails (MANDATORY)

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

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

Cross-Skill Integration

Edge Cases

Debug: OmniScript not rendering -> check activation status + element hierarchy | Data not prefilling -> verify DataRaptor Extract output mapping + JSON path | IP action failing -> check IP independently first + verify input map | Steps not showing -> review conditional visibility expressions

Notes

Dependencies (required): sf-datamapper, sf-integration-procedure | Dependencies (optional): sf-deploy, sf-flexcard, sf-omnistudio-analyze | API: 66.0 | Mode: Strict (warnings block) | Scoring: Block deployment if score < 67 | Reference docs: See references/ for element types and best practices

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 — 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.