SfSkills Domains Docs GitHub

Home / flow / flow-orchestration-patterns

flow-orchestration-patterns

Flow Orchestration design patterns — multi-stage, multi-step flows where each step is itself an autolaunched flow or a screen flow assigned to a user / queue, with Work Items appearing in users' inboxes for interactive steps.

Open the skill folder on GitHub

Flow Orchestration Patterns

Flow Orchestration is the multi-stage version of Flow — a top-level orchestration contains stages, each stage contains steps, and each step is itself a flow (autolaunched for background work, screen flow for interactive). Orchestrations are persistent: they survive across days and weeks, with users picking up assigned Work Items from their inbox, and the orchestration moves through stages as exit criteria are met.

This is the answer for processes that span multiple humans / multiple business days / multiple decision points — the kind of process that used to be a Workflow Rule chain, an Approval Process, or a confused mix of triggers and Process Builder. Orchestrations make the multi-stage shape explicit.

Summer '26: Flow Orchestration is a standard platform feature (no longer requiring a separate orchestration add-on in newly provisioned orgs). Existing orgs may still need the Flow Orchestration permission set license for assignees — confirm entitlements before go-live, but architects can treat orchestration as the default multi-stage automation surface rather than a niche add-on.

What this skill is NOT. The basic Flow runtime (single-flow execution semantics, governor limits per interview, fault paths) lives in flow/flow-best-practices. Approval Processes are a different runtime with their own UI and metadata — see admin/approval-process-design. This skill is specifically about the Orchestration metadata type and the patterns for assembling multi-stage processes from it.

Before Starting

Core Concepts

The orchestration / stage / step hierarchy

Orchestration (top-level metadata)
  │
  ├── Stage 1
  │     ├── Step 1A — Interactive (screen flow, assigned to <user/queue>)
  │     └── Step 1B — Background (autolaunched flow)
  │
  ├── Stage 2 (gated by Stage 1 completion + optional evaluation flow)
  │     ├── Step 2A — Interactive
  │     └── Step 2B — Interactive
  │
  └── Stage 3
        └── Step 3 — Background

A stage's steps run in parallel by default. A stage completes when all its steps are done. Stages run sequentially.

Interactive vs background steps

Step typeRuns asVisible to user?Use case
InteractiveScreen flow assigned to a user / queueWork Item in the assignee's inboxApproval click, form fill, document review
BackgroundAutolaunched flow, runs to completionInvisibleField updates, notifications, system integration

Mixing within a stage is normal. A "Wait for VP approval" stage might have an Interactive step (the VP's Work Item) AND a Background step (a notification Apex callout to a downstream system). Both run in parallel; stage completes when both finish.

Evaluation flows for stage transitions

The default rule "stage completes when all its steps are done" works for most orchestrations. When you need additional gating (e.g. "stage completes only if the record's status is now 'Approved'"), attach an evaluation flow to the stage's exit. The evaluation flow runs at exit-attempt time; it returns true/false, and the stage transitions only on true.

Evaluation flows are autolaunched flows that take the orchestration's context (record Id, custom variables) and return a Boolean output. They run quickly (no user interaction) and can re-check the source record's state — important for orchestrations spanning days where the record may have been updated outside the orchestration.

Work Item assignment

Each interactive step has an assignee. Salesforce supports four assignment models:

ModelConfigurationUse case
Running userDefault — whoever started the orchestrationSelf-service flows
Specific userHardcoded user referenceSmall-team / single-approver flows
QueueQueue reference; any queue member can claimWorkload-balanced approvals
Formula-derivedExpression evaluating to a user IdManager-of-running-user, region-VP-from-record-field

Formula-derived is the most powerful and most error-prone — if the formula returns null or an inactive user, the step is stuck.

Persistence and the long-running gotcha

Orchestrations are persistent across days. The orchestration state is stored on the platform; users pick up Work Items from their inbox at their pace. This is the feature.

The cost: long-running orchestrations are sensitive to changes in the underlying flow definitions. A screen flow that's modified between when a Work Item was created and when the user opens it may present a different UI than the orchestration originally specified — at best confusing, at worst broken (if the flow's input variables changed shape). Salesforce versions flow definitions, but the version-binding behavior for in-flight orchestrations isn't always intuitive.

Common Patterns

Pattern A — Linear approval chain

When to use. Document review process: Author submits → Manager reviews → VP approves → Document marked Final.

Orchestration: Document_Approval
  Stage 1: Submission
    Step: Mark Submitted (Background — sets status, fires notification)
  Stage 2: Manager Review
    Step: Manager Review Work Item (Interactive — assigned to author's manager via formula)
  Stage 3: VP Approval
    Step: VP Approval Work Item (Interactive — assigned to manager's manager)
  Stage 4: Finalize
    Step: Mark Final (Background — sets status to Final, archives)

Each stage's exit criteria: default (all steps complete). No evaluation flow needed.

Pattern B — Branching approval based on amount threshold

When to use. Expense approval where small expenses skip VP-level approval.

Orchestration: Expense_Approval
  Stage 1: Manager Review
    Step: Manager Review Work Item
    Exit evaluation flow: returns true (always — manager always reviews)

  Stage 2: VP Review (conditional)
    Step: VP Review Work Item
    Entry condition: orchestration variable Amount > 10000

  Stage 3: Finalize (always)
    Step: Mark Approved (Background)

Stage 2 is gated by an entry condition; small expenses skip directly to Stage 3. The orchestration metadata supports this via stage-level conditions.

Pattern C — Parallel steps with mixed interactive + background

When to use. Onboarding: when employee starts, simultaneously provision their accounts (background) AND have HR collect their documents (interactive).

Orchestration: Employee_Onboarding
  Stage 1: Day 1
    Step 1A: Provision Accounts (Background — Apex action calls IDP)
    Step 1B: HR Document Collection (Interactive — assigned to HR queue)
    Step 1C: Slack Welcome (Background — Slack webhook action)

  Stage 2: Week 1 Training
    Step 2: Mandatory Training Work Item (Interactive — assigned to running user)

Stage 1 has three parallel steps; stage completes when all three finish. The HR document step is the long pole; provisioning and Slack happen in seconds.

Pattern D — Long-running orchestration with re-evaluation gate

When to use. Multi-week process where the underlying record's state may change outside the orchestration (case escalation, opp loss, employee termination).

Approach. Add an evaluation flow at every stage's exit that re-checks the source record's state. If the record is in a terminal state (case closed, opp lost), the evaluation flow returns false, the orchestration is held — admins decide whether to cancel or resume.

The evaluation flow's output drives a side-decision: log the state-mismatch to a custom object, optionally email an admin, hold the orchestration.

Decision Guidance

SituationApproachReason
Single-decision approval (one user clicks Approve)Approval Process OR single-stage orchestration with one interactive stepApproval Process is older but simpler; orchestration is overkill for single-step
Multi-stage process with > 2 humans involvedOrchestration Pattern A or BOrchestration's stage / step model is built for this
Branching based on record conditionPattern B with stage entry conditionsSkip stages that don't apply
Parallel work in a single stagePattern C with mixed interactive + backgroundDefault parallel-within-stage is the right shape
Long-running with possible record-state changePattern D with evaluation flows on every stage exitRe-check at each stage boundary
Single user does everything sequentiallyScreen flow with multiple screensDon't reach for orchestration when one flow with one user fits
Background-only (no human interaction)Autolaunched flow chainOrchestration's stage model is overhead with no benefit
Stage step assigned to "the manager of the manager"Formula-derived assigneeDocumented as a recognized pattern; test for null managers
Need to cancel an in-flight orchestrationRun an autolaunched flow that completes the current step + skips the restNo direct cancel UI; orchestration must be designed with a cancel pathway
  1. Decide if orchestration is the right shape. Multi-stage, multi-human, multi-day → yes. Single user, single decision → screen flow. No human → autolaunched flow chain.
  2. Map the stages. What's the meaningful business milestone at the end of each stage?
  3. Per stage, list the steps. Interactive (user takes action) vs background (system runs). Steps within a stage run in parallel.
  4. For each interactive step, decide the assignee model. Running user / specific user / queue / formula-derived. Document the formula and test the null case.
  5. For each stage, decide if an evaluation flow is needed. Default is "all steps complete = stage complete"; add evaluation flow when additional gating is required.
  6. Plan the cancel pathway. Orchestrations have no direct cancel UI; design an admin-pathway from the start.
  7. Test the long-running case. Save an in-flight orchestration; modify a referenced flow definition; verify the orchestration still resumes correctly.

Review Checklist

Salesforce-Specific Gotchas

  1. No direct cancel UI for in-flight orchestrations. Cancel pathway must be designed in. (See references/gotchas.md § 1.)
  2. Formula-derived assignee returning null leaves the step stuck. Add fallback logic. (See references/gotchas.md § 2.)
  3. Modifying a screen-flow definition referenced by an in-flight Work Item can cause confusing UI / errors at resume time. (See references/gotchas.md § 3.)
  4. Inactive user as assignee — Work Item is created but the user can't open it. (See references/gotchas.md § 4.)
  5. Stages run sequentially, steps within a stage run in parallel — confusing this produces ordering bugs. (See references/gotchas.md § 5.)
  6. Background steps don't surface errors to users — fault path + admin notification is required (see flow/flow-error-notification-patterns). (See references/gotchas.md § 6.)
  7. Evaluation flows that throw exceptions hold the orchestration — they don't fall through to stage completion. (See references/gotchas.md § 7.)

Output Artifacts

ArtifactDescription
Orchestration metadataThe top-level orchestration with stages, steps, connectors, evaluation flows
Per-step flow definitionsEach interactive / background step is a separate flow file
Assignee documentationPer interactive step, the model + fallback for null/inactive
Cancel pathwayDocumented admin-action that cleans up in-flight orchestrations
Test planLong-running, mid-orchestration record change, assignee deactivation

Package files