Home / omnistudio / omniscript-design-patterns

omniscript-design-patterns

Use when designing or reviewing OmniScripts for guided experiences, step structure, branching, save/resume, and the boundary between OmniScript, Integration Procedures, DataRaptors, and custom LWCs. Triggers: 'omniscript design', 'too many steps in omniscript', 'save and resume omniscript', 'branching in omniscript', 'when should this be an integration procedure'. NOT for deep Integration Procedure design — use omnistudio/integration-procedures. NOT for DataRaptor design — use omnistudio/dataraptor-patterns.

v1.0.1
Salesforce Spring '25+
Updated 2026-10-03
User Experience
Operational Excellence
Reliability

omniscript
guided-experience
save-and-resume
branching
omnistudio

Open the skill folder on GitHub

Use this skill when OmniScript is the guided interaction layer for a business journey and the design needs to stay understandable for users and maintainers. The key question is not just how to assemble elements, but how to keep steps, branching, data gathering, and backend calls balanced so the script stays fast and operable.

Before Starting

What is the user journey, and how many meaningful steps does it actually require?
Which logic belongs in the guided script, and which belongs behind it in Integration Procedures, DataRaptors (Data Mappers), or Apex-backed components?
Does the experience need save and resume, conditional branching, reusable child OmniScripts, custom LWC components, or multilingual versions?
Which runtime does the org use: Omnistudio for Managed Packages or the standard runtime? Designers, metadata types, and Trailhead content differ.

Questions to Ask Before Configuring

Question	Why it matters	What a good answer adds	What proper configuration adds over just doing it
What Type, SubType, and Language will identify this OmniScript?	Only one active OmniScript may have the same Type, SubType, and Language; the metadata unique name is `Type_SubType_Language_VersionNumber`.	A naming scheme that leaves room for variants and languages.	No collision when a second team builds a similar journey.
Which parts of the journey are reused elsewhere?	A child OmniScript can be embedded only when it is marked embeddable (`isOmniScriptEmbeddable`).	Small reusable child scripts for shared steps.	One fix updates every journey that embeds the child.
How many server calls does each step make, and can one Integration Procedure serve them?	Trailhead calls Integration Procedures the best practice for data input, and an Integration Procedure Action calls "a series of actions" in one request.	One orchestrating IP per user intent.	Fewer round trips and one place to change data logic.
Does the journey need save and resume, and what must be re-checked on resume?	Save Options are a script-wide Setup panel setting; backend data can change while a session is paused.	A list of values revalidated on resume.	Resumed sessions don't submit stale eligibility or prices.
Which validations must also hold on the server?	Step validation runs in the browser; any caller that reaches the IP or Apex directly skips it.	Server-side checks for every write.	Data rules hold for API callers and guest users too.
Will the OmniScript ship as metadata (`OmniScript` type) or as DataPacks?	Enabling Omnistudio metadata can't be undone and is blocked by unique names with spaces or special characters.	A chosen deployment model before naming components.	Clean CLI deploys and diffs.

Core Concepts

OmniScript Is the Guided Experience Layer

OmniScript is strongest at user guidance, step progression, and data collection. Trailhead describes its modular architecture: the JSON structure, stylesheets, and data are kept separate, and Action elements reach data through Integration Procedures, Data Mapper actions, HTTP actions, and other tools. It gets harder to maintain when it also absorbs every transformation and integration rule.

Element Families

Family	Use for	Examples
Actions	Getting, saving, calculating, emailing	Data Mapper Extract Action, Data Mapper Post Action, Integration Procedure Action, HTTP Action, Email Action, Navigate Action
Display	Instructions and layout	Text Block, Line Break
Functions	Calculations and conditional messages	Formula, Aggregate, Messaging
Groups	Grouping on the page	Step, Block, Edit Block, Radio Group, Type Ahead Block
Inputs	User entry and selection	Text, Phone, URL, Select, Checkbox, Lookup
Omniscripts	Reusable child scripts	Embedded child OmniScript

Element names must be unique within an OmniScript (Trailhead). Labels need not be unique; Action labels appear in the Action Debugger.

Step Design Is a UX Decision and an Operations Decision

Each step should be a meaningful chunk of work. Too many tiny steps cause fatigue and operational complexity. Oversized steps cause validation and branching confusion.

Branching Must Keep a Clear Data Story

Conditional paths are often necessary, but they should still produce a predictable data JSON. Branches that change the data shape without defaults make testing and support much harder.

Versions and Activation

Only one version of an OmniScript can be active at a time. To change an active OmniScript, create a new version; the active one keeps serving users while you work (Trailhead, "Create a Simple Omniscript").

Common Patterns

Thin OmniScript, Rich Backend Services

When to use: The journey needs a guided UI, but transformations and integrations are too complex for the script layer.

How it works: Keep OmniScript focused on interaction. Put data shaping into one Integration Procedure per user intent, which calls Data Mappers and HTTP actions.

Why not the alternative: Backend-heavy scripts become slow, hard to test, and difficult to evolve.

Milestone-Based Step Design

When to use: The journey spans clear milestones such as identify, verify, select, confirm, and submit.

How it works: Group fields and decisions by milestone rather than by data model, and align validation with those checkpoints.

Reusable Child OmniScripts

When to use: Several journeys share a block of steps, such as address capture or identity verification.

How it works: Build the shared steps as their own OmniScript, mark it embeddable, and embed it with the Omniscripts element. The deployable files and naming are in references/metadata-examples.md.

Controlled Branching With Stable Defaults

When to use: User answers legitimately change later steps.

How it works: Keep branches narrow, provide a predictable default path, and keep the resulting data JSON comprehensible for downstream processing.

Decision Guidance

Situation	Recommended Approach	Reason
Guided multi-step journey with clear checkpoints	OmniScript	Best fit for guided interaction
Heavy transformation or integration logic	One Integration Procedure behind the script	Keeps the guided layer thin and the call count low
One field from Salesforce	Lookup input	Trailhead's mapping for single-field input
Fields from one object	Data Mapper Turbo Action	Simpler and faster for single-object reads
Fields from related objects	Data Mapper Extract Action, or an IP	Multi-object reads
Shared steps across journeys	Embeddable child OmniScript	One place to fix shared logic
Very custom UI dominates the experience	Custom LWC plus services	OmniScript is not always the right UX layer

Recommended Workflow

Write the journey as milestones and fix the Type, SubType, and Language for each OmniScript and child script.
Map each data need to an element using the Decision Guidance table, defaulting to one Integration Procedure Action per user intent.
Configure Setup panel options (save options, error messages) and decide what is revalidated on resume.
Build steps, test in Preview with a real Context ID, and inspect the Data JSON and the Action Debugger for every action.
Retrieve the OmniScript metadata and run python3 skills/omnistudio/omniscript-design-patterns/scripts/check_omniscript_design_patterns.py --source-dir force-app to flag step and action counts, missing embeddable flags, and non-standard unique names.
Activate the new version only after review, and record which version is active per environment.

Review Checklist

[ ] Type, SubType, and Language are unique among active OmniScripts; element names are unique within each script.
[ ] Step count and grouping reflect real user milestones.
[ ] Each step makes as few server calls as possible, normally one Integration Procedure per user intent.
[ ] Branches are narrow and leave a stable data JSON.
[ ] Save/resume behavior has explicit revalidation rules.
[ ] Every write is validated again on the server.
[ ] Shared steps live in embeddable child OmniScripts.
[ ] The team can explain why OmniScript fits better than Flow or a custom LWC for this journey.

Salesforce-Specific Gotchas

Full write-ups with sources are in references/gotchas.md.

Gotcha	One-line summary
Identity collision	Only one active OmniScript per Type, SubType, and Language.
Version activation	Changing an active script means creating and activating a new version.
Embedding	A child must be marked embeddable before another script can embed it.
Client-side validation	Step validation is UX, not a server boundary.
Call count	Many actions per step multiply round trips; prefer one orchestrating IP.
Metadata switch	Omnistudio metadata can't be turned off once enabled.
Internal objects	`OmniProcess` and `OmniProcessElement` records are internal; don't edit them with DML.

Output Artifacts

Artifact	Description
OmniScript design review	Findings on step count, branching, save/resume, and service boundaries
Journey model	Step structure, checkpoints, Type/SubType/Language plan, delegated backend responsibilities
Simplification plan	Changes that reduce script sprawl or move logic behind the guided layer

omnistudio/integration-procedures: use when the backend service orchestration is the real design focus.
lwc/custom-property-editor-for-flow: use when the problem shifts from guided journey design to custom component implementation.
admin/flow-for-admins: use when a standard Flow may be sufficient and OmniStudio might be unnecessary.