Long-Running Process Orchestration
Use this skill when a business process must span multiple Apex transactions, cannot complete within a single execution context, and requires state preservation, progress tracking, and recovery from partial failure. The skill covers Queueable chaining with bounded depth, Platform Event state machines, Finalizer-based recovery, and Continuation for async UI callouts.
Before Starting
Gather this context before working on anything in this domain:
- How many discrete steps does the process have, and are they sequential, parallel, or conditional?
- Can each step complete within a single Apex transaction (60 000 ms CPU, 100 SOQL, 150 DML)? If any step may exceed those limits, it needs its own Queueable or Batch boundary.
- Which steps involve callouts? Callout steps require
Database.AllowsCallouts on their Queueable class.
- Where does progress need to be visible — operations dashboard, record field, email notification? This shapes the checkpoint mechanism.
- What is the correct recovery behavior when step N fails? Should the whole process abort, retry step N, or skip to a compensating action?
- Is the process already partially implemented in Flow Orchestration? If so, the Apex role may be limited to a single-step callout or heavy data operation delegated from Flow.
Core Concepts
Why Single Transactions Are Insufficient
Salesforce imposes hard transaction limits per execution context: 60 000 ms CPU, 100 SOQL queries, 150 DML statements, 12 MB heap, and a 10-second total callout timeout. A process that must send 20 batched callouts, process thousands of records in sequential dependency steps, or wait for external system responses cannot fit in one transaction. Multi-step orchestration is the platform-endorsed pattern for these cases: each step runs in its own transaction with a full allocation of governor limits, and state advances through controlled async handoffs.
Queueable Chaining As A Step Sequencer
The most direct Apex orchestration mechanism is chaining Queueable jobs. Each Queueable's execute() method does its work and enqueues the next job in the sequence, passing forward a state object through the constructor. Key constraints that shape this pattern:
- Only one child Queueable may be enqueued per
execute() call (Apex Developer Guide — Queueable Apex).
AsyncOptions.MaximumQueueableStackDepth caps the chain length. The platform enforces a maximum of 5 levels in async contexts; in synchronous test contexts the default is 1. Every System.enqueueJob() call in the chain must re-pass AsyncOptions — it does not propagate automatically.
System.AsyncInfo.getCurrentQueueableStackDepth() returns the current chain depth so logic can decide whether to continue or hand off.
- Fan-out (one step spawning multiple parallel children) is not supported through chaining alone. Use Platform Events or Batch Apex for fan-out.
The Finalizer Interface For Cross-Step Recovery
The System.Finalizer interface runs in a guaranteed separate transaction after its parent Queueable completes — regardless of whether the parent succeeded or threw an uncaught exception. This is the only safe mechanism for:
- Advancing the orchestration state on failure (compensating transaction)
- Retrying a failed step up to a bounded count
- Recording a dead-letter entry when retries are exhausted
- Triggering downstream notification or monitoring
The FinalizerContext provides getResult() (SUCCESS or UNHANDLED_EXCEPTION), getException(), and getJobId(). A Finalizer may enqueue one additional Queueable. System.attachFinalizer() must be called early in the parent's execute() before any code that could throw (Apex Developer Guide — Transaction Finalizers).
Platform Event State Machine
When a process needs to cross system boundaries, tolerate external latency, or decouple step producers from step consumers, a Platform Event state machine is more flexible than direct Queueable chaining. The pattern:
- Each step completion publishes a
StepCompleted__e (or domain-specific) Platform Event with the next-step identifier and carry-forward state as payload fields.
- An Apex
after insert trigger on that event type reads the next-step field and dispatches a Queueable for the next step.
- Progress and replay position are tracked on a Custom Object record (the "process instance"), which also serves as the operational dashboard.
Platform Events decouple publish time from subscribe time, survive transaction rollbacks (events published in a rolled-back DML transaction are still delivered — this is a feature, not a bug), and allow external systems to participate as steps in the process (Platform Events Developer Guide).
Progress Tracking And Observability
A long-running process is operationally incomplete without a way to observe where each instance is and why it stopped. Checkpoint patterns:
- Custom Object record per process instance:
Status__c, CurrentStep__c, StepStartedAt__c, ErrorMessage__c, RetryCount__c. Updated at the start and end of each step.
- Platform Event broadcast for real-time dashboards or monitoring triggers.
- AsyncApexJob records are queryable by job ID for built-in Queueable status.
Step start/end timestamps enable latency monitoring per step, which surfaces performance regressions before they cause timeouts.
Continuation For Long-Running LWC Callouts
When the long-running operation is a callout initiated from Lightning UI, the Continuation class provides an async callout mechanism that does not block the user session. The controller initiates the callout by returning a Continuation object; Salesforce processes the callout asynchronously (up to 120 seconds) and invokes a callback method with the response. This is distinct from Queueable: Continuation is UI-initiated, synchronous from the user's perspective, and limited to callout contexts in LWC/Aura/Visualforce controllers (Apex Developer Guide — Continuation).
Common Patterns
Bounded Queueable Chain With State Object
When to use: A sequential process of 3–10 steps where each step is a distinct DML or callout operation, steps are ordered and have no parallelism, and the total chain depth fits within platform limits.
How it works:
- Define a serializable
ProcessState inner class or standalone class carrying: currentStep (integer or enum), recordId, retryCount, and any payload fields needed by subsequent steps.
- Each Queueable receives a
ProcessState instance, executes its step, updates the Custom Object checkpoint record, then evaluates whether to chain:
public class StepOneQueueable implements Queueable {
private final ProcessState state;
public StepOneQueueable(ProcessState state) {
this.state = state;
}
public void execute(QueueableContext ctx) {
System.attachFinalizer(new StepFinalizer(state));
// Do step work
doStepOneWork(state.recordId);
// Update checkpoint
updateCheckpoint(state.recordId, 'StepOne', 'Complete');
// Chain to next step
state.currentStep = 2;
AsyncOptions opts = new AsyncOptions();
opts.MaximumQueueableStackDepth = 5;
System.enqueueJob(new StepTwoQueueable(state), opts);
}
}
- The Finalizer handles failure — it increments
retryCount on the state object and re-enqueues the same step if retries remain, or marks the process instance as failed.
Why not the alternative: Placing all steps in a single Queueable with a switch statement runs the risk of hitting governor limits mid-step with no safe boundary. Separate Queueables give each step its own full transaction allocation.
Platform Event State Machine With Process Instance Record
When to use: The process involves external system responses between steps, steps may run minutes or hours apart, or you need strict decoupling between step producers and consumers.
How it works:
- Create a Process Instance Custom Object (
OrchestrationRun__c) with fields: Status__c (picklist: Pending/Running/Complete/Failed), CurrentStep__c (text), RetryCount__c, LastError__c.
- When launching the process, insert the record with
Status__c = 'Running' and CurrentStep__c = 'StepOne', then publish a StepAdvance__e platform event with RunId__c = record.Id and Step__c = 'StepOne'.
- The platform event trigger reads
Step__c and enqueues the appropriate Queueable:
trigger StepAdvanceTrigger on StepAdvance__e (after insert) {
for (StepAdvance__e evt : Trigger.new) {
if (evt.Step__c == 'StepOne') {
System.enqueueJob(new StepOneWorker(evt.RunId__c));
} else if (evt.Step__c == 'StepTwo') {
System.enqueueJob(new StepTwoWorker(evt.RunId__c));
}
// Additional steps...
}
}
- At the end of each worker, it updates
OrchestrationRun__c and publishes the next StepAdvance__e.
- On failure, the Finalizer updates
Status__c = 'Failed' and LastError__c.
Why not the alternative: Queueable chaining alone cannot resume after an external system delay of hours without consuming a Queueable slot waiting for the response. Platform Events decouple the step trigger from the response and survive org restarts.
Hybrid: Queueable Chain Within Steps, Platform Events Between Phases
When to use: The orchestration has distinct phases (e.g., Validation, Processing, Notification) where each phase consists of sequential sub-steps, and phases are separated by external events or significant time gaps.
How it works: Use a Queueable chain for the sub-steps within a phase; use a Platform Event to signal phase completion and trigger the next phase. The Custom Object record tracks both phase and sub-step. This hybrid keeps chain depth low per phase while maintaining decoupled phase transitions.
Decision Guidance
| Situation |
Recommended Approach |
Reason |
| 3–7 sequential steps, no external waits, completes in minutes |
Bounded Queueable chain |
Simpler, no event infrastructure needed |
| Steps separated by external system responses or human actions |
Platform Event state machine |
Decouples step timing from Apex transaction lifecycle |
| Fan-out required (one step spawns N parallel workers) |
Platform Events or Batch |
Queueable allows only one child per execution |
| Step failure should auto-retry up to N times |
Finalizer-based retry |
Only mechanism that handles all failure modes including system-level exceptions |
| Process is UI-initiated and involves a long callout |
Continuation |
Designed for async LWC/Aura callouts up to 120s |
| Step volume exceeds Queueable chain depth limits |
Batch Apex for heavy step, Queueable to orchestrate transitions |
Batch handles large data volume; Queueable manages step transitions |
| Operations team needs live process visibility |
Custom Object checkpoint + Platform Event broadcast |
Enables query-based dashboards and external monitoring |
| Process has 10+ steps or irregular branching |
Platform Event state machine with dispatch table |
Cleaner than deeply nested Queueable chain logic |
Recommended Workflow
Step-by-step instructions for an AI agent or practitioner activating this skill:
- Gather context — identify all steps, their sequencing rules, governor-limit risks per step, callout needs, and failure recovery expectations. Confirm whether the process is purely Apex or has external participants.
- Choose the primary pattern — use the Decision Guidance table above. For simple sequential processes, start with Queueable chaining; for externally-triggered or time-separated steps, use the Platform Event state machine.
- Design the state model — define the Custom Object (or state class) that will carry process instance data across transactions. Include step identifier, retry count, timestamps, and error message fields.
- Implement step boundaries — each step should be a separate Queueable class. Attach a Finalizer in every Queueable that has side effects. Pass state only through constructor fields — not static variables.
- Implement the checkpoint mechanism — update the Custom Object record at the start and end of each step. Publish a progress Platform Event if real-time dashboards are required.
- Validate — run the checker script, verify governor limit exposure per step in test scenarios, confirm Finalizer coverage, and ensure chain depth respects
MaximumQueueableStackDepth.
- Review against checklist — confirm all items in the Review Checklist are satisfied before marking implementation complete.
Review Checklist
Salesforce-Specific Gotchas
MaximumQueueableStackDepth does not propagate — setting the option on the first enqueueJob call does not carry forward to child jobs. Every subsequent enqueueJob in the chain must re-set it explicitly, or the depth guard is silently absent on all jobs beyond the first.
- Platform Events published in a rolled-back DML transaction are still delivered — this is by design. A Queueable that fails mid-transaction but already published a step-advance event will advance the state machine while leaving the DML changes rolled back, causing state inconsistency. Publish step-advance events only after confirming the DML in that step succeeded.
- Finalizer failures are silent unless monitored — the Finalizer runs in a separate transaction with its own governor limits. If the Finalizer itself hits a limit or throws, it fails without surfacing to the original job's error context. Log from the Finalizer to a Custom Object or named credential endpoint so these failures are observable.
System.AsyncInfo.getCurrentQueueableStackDepth() returns 0 in synchronous test context — test methods that call Queueables synchronously via Test.stopTest() will always see a depth of 0, so depth-guard branches that skip enqueuing will never be exercised in unit tests. Add an explicit integration test or set a low MaximumQueueableStackDepth in test context to cover boundary logic.
- Continuation is LWC/Aura/VF only — attempting to create a
Continuation from a trigger, Queueable, Batch class, or @AuraEnabled method that is not a controller action throws a runtime exception. The async callout pattern for non-UI contexts is always Queueable with Database.AllowsCallouts.
Output Artifacts
| Artifact |
Description |
| Orchestration pattern recommendation |
Decision on Queueable chain vs Platform Event state machine vs hybrid, with rationale |
| State model design |
Custom Object schema and state class fields required for this process |
| Step scaffold |
Queueable class skeletons with Finalizer, state passing, and checkpoint update |
| Platform Event trigger dispatch table |
Thin trigger routing step-advance events to the correct Queueable worker |
| Review findings |
Assessment of an existing multi-step async implementation against the review checklist |
Related Skills
apex/apex-queueable-patterns — use for single-job Queueable design, Finalizer API details, and AsyncOptions reference.
apex/platform-events-apex — use for Platform Event schema design, publish result handling, and CDC vs Platform Event selection.
apex/batch-apex-patterns — use when individual steps involve large-volume record processing that exceeds Queueable limits.
apex/async-apex — use when the question is whether Queueable, Batch, Future, or Scheduled is the right async mechanism.
apex/exception-handling — use when the broader error handling framework and logging strategy are the primary concern.
apex/governor-limits — use when steps are hitting specific limits that require redesign.
flow/orchestration-flows — use when the orchestration can be entirely managed in Flow Orchestration without Apex.
1---2name: long-running-process-orchestration3description: "Use when designing or reviewing multi-step Apex orchestration that spans multiple transactions, checkpoints state across async boundaries, or recovers from partial failure in a long-running workflow. Trigger keywords: 'multi-step Queueable chain', 'cross-transaction state', 'platform event state machine', 'Finalizer retry', 'orchestrate across transactions', 'workflow progress tracking'. NOT for single-job Queueable design (use apex-queueable-patterns), NOT for Flow Orchestration (use flow/orchestration-flows), NOT for bulk record processing where Batch Apex is the primary tool (use batch-apex-patterns)."4category: apex5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Reliability8 - Scalability9 - Operational Excellence10tags:11 - queueable12 - finalizer13 - platform-events14 - async-apex15 - orchestration16 - state-machine17 - cross-transaction18inputs:19 - "Description of the multi-step process and its steps, dependencies, and failure modes"20 - "Whether steps require callouts, DML, or external triggers to advance"21 - "Operational requirements: retry behavior, progress visibility, partial failure handling"22 - "Expected data volume per step (determines whether chaining or Batch is more appropriate)"23outputs:24 - "Orchestration pattern recommendation (Queueable chain vs Platform Event state machine vs hybrid)"25 - "Apex class scaffold with state-passing, Finalizer, and progress tracking"26 - "Review findings for existing multi-step async implementations"27 - "Decision guidance on checkpointing, retry depth, and step boundaries"28triggers:29 - how do I chain Queueable jobs across multiple transactions30 - Apex process needs to run across multiple transactions with state checkpointing31 - platform event state machine for long-running workflow32 - Finalizer interface retry pattern for Queueable failure recovery33 - track progress of a multi-step async Apex orchestration34dependencies:35 - apex/apex-queueable-patterns36 - apex/platform-events-apex37version: 1.0.038author: Pranav Nagrecha39updated: 2026-04-0640metadata:41 source: https://skillmd.com/skills/banibratachatterjee/long-running-process-orchestration42---4344# Long-Running Process Orchestration4546Use this skill when a business process must span multiple Apex transactions, cannot complete within a single execution context, and requires state preservation, progress tracking, and recovery from partial failure. The skill covers Queueable chaining with bounded depth, Platform Event state machines, Finalizer-based recovery, and Continuation for async UI callouts.4748---4950## Before Starting5152Gather this context before working on anything in this domain:5354- How many discrete steps does the process have, and are they sequential, parallel, or conditional?55- Can each step complete within a single Apex transaction (60 000 ms CPU, 100 SOQL, 150 DML)? If any step may exceed those limits, it needs its own Queueable or Batch boundary.56- Which steps involve callouts? Callout steps require `Database.AllowsCallouts` on their Queueable class.57- Where does progress need to be visible — operations dashboard, record field, email notification? This shapes the checkpoint mechanism.58- What is the correct recovery behavior when step N fails? Should the whole process abort, retry step N, or skip to a compensating action?59- Is the process already partially implemented in Flow Orchestration? If so, the Apex role may be limited to a single-step callout or heavy data operation delegated from Flow.6061---6263## Core Concepts6465### Why Single Transactions Are Insufficient6667Salesforce imposes hard transaction limits per execution context: 60 000 ms CPU, 100 SOQL queries, 150 DML statements, 12 MB heap, and a 10-second total callout timeout. A process that must send 20 batched callouts, process thousands of records in sequential dependency steps, or wait for external system responses cannot fit in one transaction. Multi-step orchestration is the platform-endorsed pattern for these cases: each step runs in its own transaction with a full allocation of governor limits, and state advances through controlled async handoffs.6869### Queueable Chaining As A Step Sequencer7071The most direct Apex orchestration mechanism is chaining Queueable jobs. Each Queueable's `execute()` method does its work and enqueues the next job in the sequence, passing forward a state object through the constructor. Key constraints that shape this pattern:7273- Only one child Queueable may be enqueued per `execute()` call (Apex Developer Guide — Queueable Apex).74- `AsyncOptions.MaximumQueueableStackDepth` caps the chain length. The platform enforces a maximum of 5 levels in async contexts; in synchronous test contexts the default is 1. Every `System.enqueueJob()` call in the chain must re-pass `AsyncOptions` — it does not propagate automatically.75- `System.AsyncInfo.getCurrentQueueableStackDepth()` returns the current chain depth so logic can decide whether to continue or hand off.76- Fan-out (one step spawning multiple parallel children) is not supported through chaining alone. Use Platform Events or Batch Apex for fan-out.7778### The Finalizer Interface For Cross-Step Recovery7980The `System.Finalizer` interface runs in a guaranteed separate transaction after its parent Queueable completes — regardless of whether the parent succeeded or threw an uncaught exception. This is the only safe mechanism for:8182- Advancing the orchestration state on failure (compensating transaction)83- Retrying a failed step up to a bounded count84- Recording a dead-letter entry when retries are exhausted85- Triggering downstream notification or monitoring8687The `FinalizerContext` provides `getResult()` (SUCCESS or UNHANDLED_EXCEPTION), `getException()`, and `getJobId()`. A Finalizer may enqueue one additional Queueable. `System.attachFinalizer()` must be called early in the parent's `execute()` before any code that could throw (Apex Developer Guide — Transaction Finalizers).8889### Platform Event State Machine9091When a process needs to cross system boundaries, tolerate external latency, or decouple step producers from step consumers, a Platform Event state machine is more flexible than direct Queueable chaining. The pattern:92931. Each step completion publishes a `StepCompleted__e` (or domain-specific) Platform Event with the next-step identifier and carry-forward state as payload fields.942. An Apex `after insert` trigger on that event type reads the next-step field and dispatches a Queueable for the next step.953. Progress and replay position are tracked on a Custom Object record (the "process instance"), which also serves as the operational dashboard.9697Platform Events decouple publish time from subscribe time, survive transaction rollbacks (events published in a rolled-back DML transaction are still delivered — this is a feature, not a bug), and allow external systems to participate as steps in the process (Platform Events Developer Guide).9899### Progress Tracking And Observability100101A long-running process is operationally incomplete without a way to observe where each instance is and why it stopped. Checkpoint patterns:102103- **Custom Object record** per process instance: `Status__c`, `CurrentStep__c`, `StepStartedAt__c`, `ErrorMessage__c`, `RetryCount__c`. Updated at the start and end of each step.104- **Platform Event broadcast** for real-time dashboards or monitoring triggers.105- **AsyncApexJob** records are queryable by job ID for built-in Queueable status.106107Step start/end timestamps enable latency monitoring per step, which surfaces performance regressions before they cause timeouts.108109### Continuation For Long-Running LWC Callouts110111When the long-running operation is a callout initiated from Lightning UI, the `Continuation` class provides an async callout mechanism that does not block the user session. The controller initiates the callout by returning a `Continuation` object; Salesforce processes the callout asynchronously (up to 120 seconds) and invokes a callback method with the response. This is distinct from Queueable: Continuation is UI-initiated, synchronous from the user's perspective, and limited to callout contexts in LWC/Aura/Visualforce controllers (Apex Developer Guide — Continuation).112113---114115## Common Patterns116117### Bounded Queueable Chain With State Object118119**When to use:** A sequential process of 3–10 steps where each step is a distinct DML or callout operation, steps are ordered and have no parallelism, and the total chain depth fits within platform limits.120121**How it works:**1221. Define a serializable `ProcessState` inner class or standalone class carrying: `currentStep` (integer or enum), `recordId`, `retryCount`, and any payload fields needed by subsequent steps.1232. Each Queueable receives a `ProcessState` instance, executes its step, updates the Custom Object checkpoint record, then evaluates whether to chain:124125```apex126public class StepOneQueueable implements Queueable {127 private final ProcessState state;128129 public StepOneQueueable(ProcessState state) {130 this.state = state;131 }132133 public void execute(QueueableContext ctx) {134 System.attachFinalizer(new StepFinalizer(state));135136 // Do step work137 doStepOneWork(state.recordId);138139 // Update checkpoint140 updateCheckpoint(state.recordId, 'StepOne', 'Complete');141142 // Chain to next step143 state.currentStep = 2;144 AsyncOptions opts = new AsyncOptions();145 opts.MaximumQueueableStackDepth = 5;146 System.enqueueJob(new StepTwoQueueable(state), opts);147 }148}149```1501513. The Finalizer handles failure — it increments `retryCount` on the state object and re-enqueues the same step if retries remain, or marks the process instance as failed.152153**Why not the alternative:** Placing all steps in a single Queueable with a `switch` statement runs the risk of hitting governor limits mid-step with no safe boundary. Separate Queueables give each step its own full transaction allocation.154155### Platform Event State Machine With Process Instance Record156157**When to use:** The process involves external system responses between steps, steps may run minutes or hours apart, or you need strict decoupling between step producers and consumers.158159**How it works:**1601. Create a Process Instance Custom Object (`OrchestrationRun__c`) with fields: `Status__c` (picklist: Pending/Running/Complete/Failed), `CurrentStep__c` (text), `RetryCount__c`, `LastError__c`.1612. When launching the process, insert the record with `Status__c = 'Running'` and `CurrentStep__c = 'StepOne'`, then publish a `StepAdvance__e` platform event with `RunId__c = record.Id` and `Step__c = 'StepOne'`.1623. The platform event trigger reads `Step__c` and enqueues the appropriate Queueable:163164```apex165trigger StepAdvanceTrigger on StepAdvance__e (after insert) {166 for (StepAdvance__e evt : Trigger.new) {167 if (evt.Step__c == 'StepOne') {168 System.enqueueJob(new StepOneWorker(evt.RunId__c));169 } else if (evt.Step__c == 'StepTwo') {170 System.enqueueJob(new StepTwoWorker(evt.RunId__c));171 }172 // Additional steps...173 }174}175```1761774. At the end of each worker, it updates `OrchestrationRun__c` and publishes the next `StepAdvance__e`.1785. On failure, the Finalizer updates `Status__c = 'Failed'` and `LastError__c`.179180**Why not the alternative:** Queueable chaining alone cannot resume after an external system delay of hours without consuming a Queueable slot waiting for the response. Platform Events decouple the step trigger from the response and survive org restarts.181182### Hybrid: Queueable Chain Within Steps, Platform Events Between Phases183184**When to use:** The orchestration has distinct phases (e.g., Validation, Processing, Notification) where each phase consists of sequential sub-steps, and phases are separated by external events or significant time gaps.185186**How it works:** Use a Queueable chain for the sub-steps within a phase; use a Platform Event to signal phase completion and trigger the next phase. The Custom Object record tracks both phase and sub-step. This hybrid keeps chain depth low per phase while maintaining decoupled phase transitions.187188---189190## Decision Guidance191192| Situation | Recommended Approach | Reason |193|---|---|---|194| 3–7 sequential steps, no external waits, completes in minutes | Bounded Queueable chain | Simpler, no event infrastructure needed |195| Steps separated by external system responses or human actions | Platform Event state machine | Decouples step timing from Apex transaction lifecycle |196| Fan-out required (one step spawns N parallel workers) | Platform Events or Batch | Queueable allows only one child per execution |197| Step failure should auto-retry up to N times | Finalizer-based retry | Only mechanism that handles all failure modes including system-level exceptions |198| Process is UI-initiated and involves a long callout | Continuation | Designed for async LWC/Aura callouts up to 120s |199| Step volume exceeds Queueable chain depth limits | Batch Apex for heavy step, Queueable to orchestrate transitions | Batch handles large data volume; Queueable manages step transitions |200| Operations team needs live process visibility | Custom Object checkpoint + Platform Event broadcast | Enables query-based dashboards and external monitoring |201| Process has 10+ steps or irregular branching | Platform Event state machine with dispatch table | Cleaner than deeply nested Queueable chain logic |202203---204205## Recommended Workflow206207Step-by-step instructions for an AI agent or practitioner activating this skill:2082091. **Gather context** — identify all steps, their sequencing rules, governor-limit risks per step, callout needs, and failure recovery expectations. Confirm whether the process is purely Apex or has external participants.2102. **Choose the primary pattern** — use the Decision Guidance table above. For simple sequential processes, start with Queueable chaining; for externally-triggered or time-separated steps, use the Platform Event state machine.2113. **Design the state model** — define the Custom Object (or state class) that will carry process instance data across transactions. Include step identifier, retry count, timestamps, and error message fields.2124. **Implement step boundaries** — each step should be a separate Queueable class. Attach a Finalizer in every Queueable that has side effects. Pass state only through constructor fields — not static variables.2135. **Implement the checkpoint mechanism** — update the Custom Object record at the start and end of each step. Publish a progress Platform Event if real-time dashboards are required.2146. **Validate** — run the checker script, verify governor limit exposure per step in test scenarios, confirm Finalizer coverage, and ensure chain depth respects `MaximumQueueableStackDepth`.2157. **Review against checklist** — confirm all items in the Review Checklist are satisfied before marking implementation complete.216217---218219## Review Checklist220221- [ ] Each step is implemented as a separate Queueable with its own transaction boundary.222- [ ] `System.attachFinalizer()` is called at the start of every Queueable `execute()` method with side effects.223- [ ] `AsyncOptions.MaximumQueueableStackDepth` is set on every `System.enqueueJob()` call in a chain.224- [ ] `System.AsyncInfo.getCurrentQueueableStackDepth()` is used to guard against exceeding the cap.225- [ ] State is passed through serializable constructor fields — no static variables cross transaction boundaries.226- [ ] A Custom Object or equivalent checkpoint record tracks the current step, retry count, and error state.227- [ ] Finalizer retry logic increments a counter and aborts after a configurable maximum.228- [ ] Platform Event triggers are thin and delegate heavy work to Queueable workers.229- [ ] Callout Queueables implement `Database.AllowsCallouts`.230- [ ] Test classes use `Test.startTest()` / `Test.stopTest()` boundaries and verify the Custom Object checkpoint state.231232---233234## Salesforce-Specific Gotchas2352361. **`MaximumQueueableStackDepth` does not propagate** — setting the option on the first `enqueueJob` call does not carry forward to child jobs. Every subsequent `enqueueJob` in the chain must re-set it explicitly, or the depth guard is silently absent on all jobs beyond the first.2372. **Platform Events published in a rolled-back DML transaction are still delivered** — this is by design. A Queueable that fails mid-transaction but already published a step-advance event will advance the state machine while leaving the DML changes rolled back, causing state inconsistency. Publish step-advance events only after confirming the DML in that step succeeded.2383. **Finalizer failures are silent unless monitored** — the Finalizer runs in a separate transaction with its own governor limits. If the Finalizer itself hits a limit or throws, it fails without surfacing to the original job's error context. Log from the Finalizer to a Custom Object or named credential endpoint so these failures are observable.2394. **`System.AsyncInfo.getCurrentQueueableStackDepth()` returns 0 in synchronous test context** — test methods that call Queueables synchronously via `Test.stopTest()` will always see a depth of 0, so depth-guard branches that skip enqueuing will never be exercised in unit tests. Add an explicit integration test or set a low `MaximumQueueableStackDepth` in test context to cover boundary logic.2405. **Continuation is LWC/Aura/VF only** — attempting to create a `Continuation` from a trigger, Queueable, Batch class, or `@AuraEnabled` method that is not a controller action throws a runtime exception. The async callout pattern for non-UI contexts is always Queueable with `Database.AllowsCallouts`.241242---243244## Output Artifacts245246| Artifact | Description |247|---|---|248| Orchestration pattern recommendation | Decision on Queueable chain vs Platform Event state machine vs hybrid, with rationale |249| State model design | Custom Object schema and state class fields required for this process |250| Step scaffold | Queueable class skeletons with Finalizer, state passing, and checkpoint update |251| Platform Event trigger dispatch table | Thin trigger routing step-advance events to the correct Queueable worker |252| Review findings | Assessment of an existing multi-step async implementation against the review checklist |253254---255256## Related Skills257258- `apex/apex-queueable-patterns` — use for single-job Queueable design, Finalizer API details, and `AsyncOptions` reference.259- `apex/platform-events-apex` — use for Platform Event schema design, publish result handling, and CDC vs Platform Event selection.260- `apex/batch-apex-patterns` — use when individual steps involve large-volume record processing that exceeds Queueable limits.261- `apex/async-apex` — use when the question is whether Queueable, Batch, Future, or Scheduled is the right async mechanism.262- `apex/exception-handling` — use when the broader error handling framework and logging strategy are the primary concern.263- `apex/governor-limits` — use when steps are hitting specific limits that require redesign.264- `flow/orchestration-flows` — use when the orchestration can be entirely managed in Flow Orchestration without Apex.