Orchestration Flows

Use this skill when the business process spans time, people, and system boundaries in a way that normal record-triggered or screen flows do not handle cleanly. Flow Orchestration is the right tool when a process needs explicit stage progression, work assignment, and observability across days or weeks — instead of pretending the whole journey happens in one synchronous transaction.

Orchestration is NOT "Flow with more canvas space." It adds operational overhead (stages, work items, monitoring surface) that is valuable ONLY when the business process genuinely has time gaps, multi-user handoffs, and stage-by-stage observability requirements. Using it for simple automation is like using a message queue for in-process function calls — the overhead without the payoff.

Before Starting

Check for salesforce-context.md in the project root. If present, read it first.

Gather if not available:

• Is the process actually long-running (hours to weeks) or multi-user, or could a standard Flow handle it more simply?
• Which parts of the process are background automation, and which parts create work items for humans?
• What must happen when a step is delayed, reassigned, fails, or needs recovery after a long wait?
• Will this process replace an existing Approval Process? (If yes, consult automation-migration-router --source-type approval_process first.)
• What's the expected number of concurrent in-flight instances? (Affects monitoring design and licensing — Flow Orchestration has usage limits.)

Core Concepts

Orchestration Is For Process Lifecycles, Not Just Automation Steps

Regular Flows are good at single execution paths. Orchestration becomes useful when the process needs explicit lifecycle management across stages, users, and time gaps. Treat it as process architecture — stages = milestones visible to operations; steps = work units that can be monitored; transitions = the contract between stages.

The litmus test: "Do I need a view of where every in-flight instance is currently stuck, who owns the next action, and what intervention is required?" If yes, Orchestration. If the answer is "we'll figure it out from the Flow Interview Log", a regular Flow is sufficient.

Stages And Steps Need Clear Ownership

Stages should represent meaningful process milestones (not just "next page"). Steps should represent work that can be monitored, assigned, and completed. If stage boundaries are vague, monitoring and recovery become unclear — admins see "instance stuck in Stage 2" but don't know what Stage 2 actually represents to the business.

Rule of thumb: every stage name should be a noun phrase a business owner recognizes. "Credit Check" yes. "Stage2" no. "Processing" no. "Financial Review" yes.

Interactive And Background Work Should Be Designed Differently

Human work items need assignment, visibility, escalation, and reassignment. Background steps need idempotency, fault handling, and service-level expectations. Orchestration only helps if those two concerns are designed deliberately — NOT if you treat all steps as "Flow steps" and ignore the difference.

Monitoring Is Part Of The Design, Not an Afterthought

A long-running process is incomplete unless operations teams can see where instances are stuck, who owns the next action, and how to resume or intervene. Orchestration surfaces include:

• Work Items tab — all pending human work items, with filters by assignee, stage, and age.
• Flow Orchestration Work Items List View — customizable per-persona views of pending work.
• Orchestration Error Email — delivered to the Process Automation user when a stage fails.
• Custom dashboards — built on FlowOrchestrationInstance + FlowOrchestrationWorkItem sObjects.

If operations isn't going to look at any of these, the Orchestration was probably wrong — a standard Flow with good fault handling would have served. Design the monitoring surface BEFORE building the Orchestration, not after.

Common Patterns

Pattern 1: Stage-Based Onboarding Or Fulfillment

When to use: A business journey moves through clear milestones with a mix of automated and human tasks. Think customer onboarding, employee hiring, product fulfillment.

Structure:

Orchestration: Customer_Onboarding
├── Stage 1: Application_Received (background)
│   ├── Step: Validate_Application (auto-launched Flow)
│   └── Step: Route_To_Underwriting (background assignment logic)
├── Stage 2: Underwriting (interactive)
│   ├── Work Item: Underwriter Review (assigned to queue)
│   └── Work Item: Senior Underwriter Approval (conditional on amount > $100k)
├── Stage 3: Contract_Generation (background)
│   ├── Step: Generate_Contract (Conga / DocuSign action)
│   └── Step: Send_To_Customer
└── Stage 4: Activation (background)
    └── Step: Provision_Services

Why not the alternative: A single standard Flow becomes brittle when it tries to model waits, approvals, and manual follow-up inside one execution path. Every Pause element in a non-Orchestration Flow is a hack around the lack of stage awareness.

Pattern 2: Background Step Plus Human Review

When to use: System work should prepare data and then hand it to a reviewer or fulfiller.

Structure:

Stage: Data_Prep (background)
└── Step: Fetch_External_Data (HTTP callout via External Services)
└── Step: Normalize_And_Score (auto-launched Flow calling Apex)

Stage: Human_Review (interactive)
└── Work Item: Reviewer_Decision (assigned to queue, due-date = now + 2 business days)
    └── On complete → transition to next stage
    └── On overdue → escalation auto-launched Flow

Why not the alternative: Making every step human-visible slows the process and reduces automation value. Background steps should be invisible to reviewers unless something goes wrong.

Pattern 3: Escalation To Apex Or Another Orchestrator

When to use: The process needs heavy integration logic, very large data movement, or transaction behavior beyond Flow's fit.

Signals: Orchestration's background steps are full of @future / Queueable invocations; the stage boundaries are really Apex transaction boundaries; the operations team is monitoring Apex job status more than the Orchestration surface.

Approach: Keep Orchestration for human lifecycle management only. Move heavy system-work stages to standalone Apex (Batch, Queueable, Platform Events) that reports back to Orchestration via custom events or Flow invocations. Orchestration becomes a thin coordinator; Apex does the work.

Pattern 4: Replace Legacy Approval Process

When to use: Migrating from a multi-stage Approval Process with post-approval automation.

Structure: Each Approval Step becomes a Stage in Orchestration; Initial Submission Actions become pre-stage background work; Final Approval Actions become post-stage background work. The migration is NOT automatic — see automation-migration-router --source-type approval_process for the decision tree.

Not every approval should migrate: single-step, single-assignee approvals are better left as Approval Processes (simpler, deployed as one metadata unit). Complex multi-step approvals with cross-object routing and recall semantics are where Orchestration shines.

Decision Guidance

Well-Architected Pillar Mapping

• Reliability — orchestration's recovery semantics (resume stuck instance, reassign work item, rerun failed stage) are core reliability affordances. Findings in this area are P0 when observability is missing.
• Scalability — Orchestration has per-org usage limits (in-flight instances, work items per day). Designs that assume unlimited concurrency will break at scale.
• Operational Excellence — the monitoring surface IS the OpsEx surface. Orchestration without custom work-item list views, dashboards, or stuck-instance alerts is an OpsEx debt.

Review Checklist

• The use case genuinely requires long-running or multi-user process control.
• Stages represent real business milestones, not arbitrary canvas grouping.
• Human steps have clear assignment, escalation, and completion ownership.
• Background steps are idempotent and fault-aware.
• Monitoring and intervention expectations were designed before launch.
• Custom work-item list views exist for the relevant personas.
• Orchestration Error Email recipient is a monitored mailbox.
• The team considered whether standard Flow or Apex would be simpler.
• Per-org Orchestration usage limits have been checked against expected load.

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, licensed features, expected load, and existing automation
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Common Patterns above; map stages to business milestones
4. Validate — run the skill's checker script and verify against the Review Checklist above
5. Document — record any deviations from standard patterns and update the template if needed

Salesforce-Specific Gotchas

1. Orchestration is not a better record-triggered flow by default — it adds operational structure, which is useful only when the process truly spans time and users.
2. Poor stage boundaries create monitoring noise — if stages do not map to real milestones, work-item visibility becomes hard to act on.
3. Interactive steps are operations work, not just UI — assignment, backlog management, and reassignment need ownership from the start.
4. Long-running processes still need failure design — a stuck orchestration instance is an operational incident, not a cosmetic problem.
5. Work Item due dates are on business days, not calendar days by default — test with your org's business-hours configuration; surprise escalation timing is a common go-live bug.
6. Orchestration Error Email goes to the Process Automation user — audit the mailbox annually; orchestration errors are harder to notice than Flow fault emails.
7. In-flight instances survive a Flow version update ONLY if the new version is backward-compatible — breaking stage/step changes require explicit migration logic. Plan deprecation windows.
8. Per-org concurrent-orchestration limits exist — consult Salesforce Help for current caps (they vary by edition and have changed across releases); design load-shedding if approaching limits.
9. Work items do not auto-close on record deletion — delete the triggering record and the work item lingers in "In Progress" forever. Build a cleanup job or set explicit completion handlers.
10. Orchestration invoked from record-triggered Flow still fires per record — a bulk insert triggers one Orchestration instance per record. Scale accordingly.

Proactive Triggers

Surface these WITHOUT being asked:

• Orchestration used for single-user, single-save automation → Flag as High. This is overkill; convert to standard record-triggered Flow.
• Work items with no assignee rule (all go to a default queue with no members) → Flag as Critical. Work will pile up in the void.
• No custom list view for pending work items → Flag as High. Operations can't monitor what they can't see.
• Orchestration Error Email recipient is inactive or unset → Flag as Critical. Stage failures disappear silently.
• Background step with no fault-handling branch → Flag as High. Failed step = stuck instance forever.
• Stage name that doesn't match a business-owner's vocabulary → Flag as Medium. Naming debt; fix during design reviews.
• Orchestration replacing a simple Approval Process (single-step, single-assignee) → Flag as Medium. Re-evaluate; the simpler tool may fit better.
• No plan for handling stuck in-flight instances during a Salesforce release upgrade → Flag as High. Regression risk on release day.

Output Artifacts

Related Skills

• flow/fault-handling — use when error-routing and recovery are the immediate concern inside a step or subflow.
• flow/auto-launched-flow-patterns — the background-step flows that Orchestration invokes live here.
• flow/subflows-and-reusability — when Orchestration stages should factor work into reusable subflows.
• admin/approval-processes — use when the process is really about approval routing rather than broader orchestration.
• apex/async-apex — use when the system-work portions need more control than Flow should carry.
• standards/decision-trees/automation-selection.md — upstream decision tree routing Orchestration vs alternatives.