Skip to content

UTIL_AsyncChain.ChainBuilder ​

Class · Group: Async

Learn it: Fast Start - Async Processing and Async Processing guide

apex
global inherited sharing class UTIL_AsyncChain.ChainBuilder

Fluent builder for configuring and executing an async chain. Provides methods for adding steps, setting context, configuring error/completion handlers, and executing the chain.

Example

apex
String executionId = UTIL_AsyncChain.newChain('OrderProcessing')
    .then(new ValidateOrderStep())
    .then(new ProcessPaymentStep())
    .withInitialContext('orderId', order.Id)
    .onError(new NotifyAdminStep())
    .onComplete(new SendConfirmationStep())
    .execute();

Methods ​

MethodDescription
global UTIL_AsyncChain.ChainBuilder allowRestart()Declares this chain safe to restart from its first step.
global String execute()Executes the chain under a tracking id of its own, created by the framework.
global String execute(String correlationId)Executes the chain under the supplied correlation id, which becomes the run's own tracking id.
global UTIL_AsyncChain.ChainBuilder onComplete(IF_Chain.Step completionHandlerStep)Registers a completion handler step that executes ONLY when every step in the chain completes successfully.
global UTIL_AsyncChain.ChainBuilder onError(IF_Chain.Step errorHandlerStep)Registers an error handler step that executes when any step fails (unless the failing step has continueOnError set to true).
global UTIL_AsyncChain.ChainBuilder then(IF_Chain.Step step)Appends a step to the end of the chain.
global UTIL_AsyncChain.ChainBuilder then(IF_Chain.Step step, Boolean continueOnError)Appends a step to the chain with explicit control over error continuation.
global UTIL_AsyncChain.ChainBuilder withAsyncOptions(AsyncOptions options)Sets the AsyncOptions controlling queueable stack depth.
global UTIL_AsyncChain.ChainBuilder withDeduplicationKey(String deduplicationKey)Guards against two overlapping runs of the same logical chain.
global UTIL_AsyncChain.ChainBuilder withDelayMinutes(Integer minutes)Defers the chain's first step by the given number of minutes.
global UTIL_AsyncChain.ChainBuilder withInitialContext(String key, Object value)Seeds the chain context with an initial key-value pair before execution begins.
global UTIL_AsyncChain.ChainBuilder withMaxContextSize(Integer maximumSize)Sets the maximum serialized context size in characters.
global UTIL_AsyncChain.ChainBuilder withMaxSteps(Integer maximumSteps)Sets the maximum number of steps the chain is allowed to execute.

allowRestart ​

apex
global UTIL_AsyncChain.ChainBuilder allowRestart()

Declares this chain safe to restart from its first step. A restart re-runs EVERY step, so declare it only when the whole chain can run twice without doubling its side effects. The declaration is written on the run record at start, together with a copy of the initial context as the chain was built. The Chain Monitor offers its restart action only for such runs. A restart uses that saved copy, never the changed context a partial run left behind. It is off by default, so restart stays hidden until the author turns it on. The declaration never changes how the chain runs.

Returns UTIL_AsyncChain.ChainBuilder — This builder, for chaining.

Example

apex
String runId = UTIL_AsyncChain.newChain('NightlyAccountSync')
    .then(new SyncStep())
    .allowRestart()
    .execute();

execute ​

apex
global String execute()

Executes the chain under a tracking id of its own, created by the framework. The launching transaction may already have an active correlation ID. If it does, the run records that ID as the one it was launched under. It also keeps the transaction's root correlation ID (the ID of the action that started the work), and writes one entry in the launcher's log that names the new run. If there is no active correlation ID, the run starts its own action and is its own root. Saves the chain configuration and queues the first step. A step or a handler of another chain may call this too; see the overload for what a launch from inside a chain does.

Returns String — The ID of the AsyncChainExecution__c record tracking this chain.

Throws

ExceptionDescription
UTIL_Exceptions.IllegalStateExceptionIf the serialized step list exceeds the StepLog__c field capacity less the per-step runtime reserve, or if a launch from inside a step or handler of another chain would nest too deep or find no room (see the correlation-ID overload this method delegates to).

Example

apex
String executionId = UTIL_AsyncChain.newChain('MyChain')
    .then(new MyStep())
    .execute();
apex
global String execute(String correlationId)

Executes the chain under the supplied correlation id, which becomes the run's own tracking id. The run records three things. First, the correlation ID active in this transaction, as the ID it was launched under (null when none is active). Second, the transaction's root correlation ID (the ID of the action that started the work) as its own root: the active correlation ID when no root exists yet, or the supplied ID when neither exists. Third, the transaction's full logging context, stored under the supplied ID, so every step logs with the run's ID and the action's root. A run launched while a correlation ID is active is announced once in the launcher's log. Saves the chain configuration and queues the first step.

A run may be launched from inside a step, or from a completion or error handler, of another chain. Then it is recorded with that run's id as the id it was launched under. It sits one level below that run (chains may nest at most five levels deep). The launching run and step remember it, so a retry of that step gets the same run back instead of a second one. One chain may be launched per step or handler.

A run may also be launched from inside any other queueable job. A job started from inside a running job whose group of jobs (the jobs queued one from another, from the same first job) already has a maximum queueable stack depth takes over that maximum and cannot set its own. So the first step of a chain launched there runs under the launching group's maximum: the launching chain's, or the one the other job was queued with. The framework's default maximum leaves room for that inside a chain. A launch that would find no room, would nest too deep, or comes from a job that has already added its one queueable job, is refused before anything is written. Inside a trigger fired by a save that a queueable job makes, the platform does not let the framework read the depth of the running job. The job may be a chain step or any other job. A job queued from there starts a new group of jobs, so the chain sets its own maximum as a launch outside any job does. A chain launched this way from a step's trigger is still recorded as launched under the step's run and remembered by that step. If the platform refuses the chain's first job anyway, the run record is deleted and the platform's exception reaches the caller, so no Running run is ever left without a job.

Parameters

ParameterTypeDescription
correlationIdStringThe correlation ID to attach to all log entries for this chain.

Returns String — The ID of the AsyncChainExecution__c record tracking this chain.

Throws

ExceptionDescription
UTIL_Exceptions.IllegalStateExceptionIf the serialized step list exceeds the StepLog__c field capacity less the per-step runtime reserve (a chain that cannot persist its step list intact for its whole life must fail at definition time, never by silently truncating the persisted JSON); or if the supplied correlation ID is already attached to another chain run, since a run owns its correlation exclusively; or if the launch runs inside a step or handler of another chain and would nest deeper than five levels, find no spare queueable stack level for its first step, follow another launch from the same step or handler in the same transaction, follow a queueable job that step or handler already added, or start a different chain from a step or handler that launched one before; or if the launch runs inside another queueable job that has already added its one queueable job, or whose group of jobs has no spare queueable stack level for the first step.

Example

apex
String executionId = UTIL_AsyncChain.newChain('MyChain')
    .then(new MyStep())
    .execute('my-correlation-id');

onComplete ​

apex
global UTIL_AsyncChain.ChainBuilder onComplete(IF_Chain.Step completionHandlerStep)

Registers a completion handler step that executes ONLY when every step in the chain completes successfully. The completion handler does NOT run when the chain terminates in failure (i.e. when a step returns a failed StepResult OR throws and the step is not marked continueOnError).

Failure-path handler is a separate registration. To run a step on failure, register an error handler via .onError(...). The two handlers are mutually exclusive at runtime: exactly one of them fires per chain (success → onComplete, failure → onError), and neither fires if the chain is aborted by the framework kill switch. If you need "always-runs" cleanup (e.g. release a row lock, close a session), put the cleanup inside the final step's work() body and use continueOnError = true on the step before it, so the final step runs regardless of upstream failures.

Parameters

ParameterTypeDescription
completionHandlerStepIF_Chain.StepThe IF_Chain.Step to execute on successful completion.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
UTIL_AsyncChain.newChain('MyChain')
    .then(new ProcessStep())
    .onComplete(new SendConfirmationStep())   // success-only
    .onError(new NotifyAdminStep())           // failure-only
    .execute();

onError ​

apex
global UTIL_AsyncChain.ChainBuilder onError(IF_Chain.Step errorHandlerStep)

Registers an error handler step that executes when any step fails (unless the failing step has continueOnError set to true).

Parameters

ParameterTypeDescription
errorHandlerStepIF_Chain.StepThe IF_Chain.Step to execute on failure. Receives the chain context with the failure details.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
UTIL_AsyncChain.newChain('MyChain')
    .then(new RiskyStep())
    .onError(new NotifyAdminStep())
    .execute();

then ​

apex
global UTIL_AsyncChain.ChainBuilder then(IF_Chain.Step step)

Appends a step to the end of the chain.

Parameters

ParameterTypeDescription
stepIF_Chain.StepThe IF_Chain.Step implementation to add.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
UTIL_AsyncChain.newChain('MyChain')
    .then(new FirstStep())
    .then(new SecondStep())
    .execute();
apex
global UTIL_AsyncChain.ChainBuilder then(IF_Chain.Step step, Boolean continueOnError)

Appends a step to the chain with explicit control over error continuation. Use this overload for IF_Chain.Step implementations that cannot extend ChainStep.

Parameters

ParameterTypeDescription
stepIF_Chain.StepThe IF_Chain.Step implementation to add.
continueOnErrorBooleanWhen true, the chain continues past this step's failure.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
UTIL_AsyncChain.newChain('MyChain')
    .then(new CriticalStep())
    .then(new OptionalStep(), true)
    .then(new FinalStep())
    .execute();

withAsyncOptions ​

apex
global UTIL_AsyncChain.ChainBuilder withAsyncOptions(AsyncOptions options)

Sets the AsyncOptions controlling queueable stack depth. When provided, these options override the framework's default maximum. The default is one level per step, one for the first hop, and five more for the chains those steps may launch. Inside a chain, it is counted from the launching job's depth. In tests, pass options with an explicit maximumQueueableStackDepth that matches the expected chain depth, so the queued jobs run one after another within Test.startTest/stopTest. Inside a step or a handler of another chain, the options apply from the chain's second hop on. The first hop uses the launching chain's maximum, because the platform does not let a running job change it. So a duplicateSignature set here is not applied to that hop. The platform keeps counting depth from the launching job's depth. So a maximum set here for a chain launched from a step must include that depth, as the framework's default does. A maximum sized for a launch outside any chain runs out at a later hop and stalls the run.

Parameters

ParameterTypeDescription
optionsAsyncOptionsThe AsyncOptions to use for queueable enqueuing.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
AsyncOptions options = new AsyncOptions();
options.maximumQueueableStackDepth = 4;
UTIL_AsyncChain.newChain('MyChain')
    .then(new Step1()).then(new Step2()).then(new Step3())
    .withAsyncOptions(options)
    .execute();

withDeduplicationKey ​

apex
global UTIL_AsyncChain.ChainBuilder withDeduplicationKey(String deduplicationKey)

Guards against two overlapping runs of the same logical chain. While a run holds the key, a second execute() with the same key returns the active run's Id instead of starting a duplicate. Any terminal status releases the key in the same update, so running the chain again after it ends is allowed on purpose. A Stalled run still holds its key until it is recovered or resolved. The key is stored exactly as given. The platform's unique text field ignores case, so keys that differ only in case clash. Chains with no steps complete at once and never hold a key. This is not the same as ChainContext.idempotencyKey(), which makes replay-safe keys for your own step side effects. This method stops a second run from starting at all.

Parameters

ParameterTypeDescription
deduplicationKeyStringNon-blank key, at most 255 characters: for example a schedule name or a template like 'nightly-sync-' + recordId.

Returns UTIL_AsyncChain.ChainBuilder — This builder, for chaining.

Example

apex
String runId = UTIL_AsyncChain.newChain('NightlyAccountSync')
    .then(new SyncStep())
    .withDeduplicationKey('nightly-account-sync')
    .execute();

withDelayMinutes ​

apex
global UTIL_AsyncChain.ChainBuilder withDelayMinutes(Integer minutes)

Defers the chain's first step by the given number of minutes. This is best-effort: the platform enqueues the first step with a Queueable delay, so the chain shows as Running with zero completed steps in the Chain Monitor until the delay ends. If the org has turned off Queueable delay, the first step runs at once instead. The value is kept within the platform range of 0 to 10 minutes; a null or zero delay is a no-op. Only the first step is delayed; every later step runs as soon as the step before it finishes.

Parameters

ParameterTypeDescription
minutesIntegerThe delay before the first step, in minutes (clamped to 0 to 10). Null is a no-op.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
UTIL_AsyncChain.newChain('NightlyRollup')
    .then(new AggregateStep())
    .withDelayMinutes(5)
    .execute();

withInitialContext ​

apex
global UTIL_AsyncChain.ChainBuilder withInitialContext(String key, Object value)

Seeds the chain context with an initial key-value pair before execution begins. Each call adds one more key-value pair to the initial context map.

Parameters

ParameterTypeDescription
keyStringThe context key.
valueObjectThe context value.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
UTIL_AsyncChain.newChain('MyChain')
    .withInitialContext('recordId', record.Id)
    .withInitialContext('batchSize', 200)
    .then(new ProcessStep())
    .execute();

withMaxContextSize ​

apex
global UTIL_AsyncChain.ChainBuilder withMaxContextSize(Integer maximumSize)

Sets the maximum serialized context size in characters. Prevents context overflow from storing large object graphs. Default: 32768.

Parameters

ParameterTypeDescription
maximumSizeIntegerThe maximum context size in characters.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
UTIL_AsyncChain.newChain('LargeContextChain')
    .withMaxContextSize(65536)
    .then(new DataHeavyStep())
    .execute();

withMaxSteps ​

apex
global UTIL_AsyncChain.ChainBuilder withMaxSteps(Integer maximumSteps)

Sets the maximum number of steps the chain is allowed to execute. Prevents runaway chains from consuming unlimited resources. Default: 50.

Parameters

ParameterTypeDescription
maximumStepsIntegerThe maximum number of steps permitted.

Returns UTIL_AsyncChain.ChainBuilder — This ChainBuilder for method chaining.

Example

apex
UTIL_AsyncChain.newChain('ShortChain')
    .withMaxSteps(10)
    .then(new MyStep())
    .execute();