UTIL_AsyncChain.ChainBuilder

Class

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.

Since: 1.0

Example:

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

---

Methods

Method	Description
global String execute()	Executes the chain with an auto-generated correlation ID.
global String execute(String correlationId)	Executes the chain with a caller-supplied correlation ID for log tracing.
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 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.

---

Method Details

execute

global String execute()

Executes the chain with an auto-generated correlation ID. Persists the chain configuration and enqueues the first step.

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

Since: 1.0

Example:

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

execute

global String execute(String correlationId)

Executes the chain with a caller-supplied correlation ID for log tracing. Persists the chain configuration and enqueues the first step.

Parameters:

• correlationId (String) - The correlation ID to attach to all log entries for this chain.

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

Since: 1.0

Example:

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

onComplete

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. Subscribers needing "always-runs" cleanup (e.g. release a row lock, close a session) should 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:

• completionHandlerStep (IF_Chain.Step) - The IF_Chain.Step to execute on successful completion.

Returns: UTIL_AsyncChain.ChainBuilder - This ChainBuilder for method chaining.

Since: 1.0

Example:

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

onError

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:

• errorHandlerStep (IF_Chain.Step) - The IF_Chain.Step to execute on failure. Receives the chain context with the failure details.

Returns: UTIL_AsyncChain.ChainBuilder - This ChainBuilder for method chaining.

Since: 1.0

Example:

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

then

global UTIL_AsyncChain.ChainBuilder then(IF_Chain.Step step)

Appends a step to the end of the chain.

Parameters:

• step (IF_Chain.Step) - The IF_Chain.Step implementation to add.

Returns: UTIL_AsyncChain.ChainBuilder - This ChainBuilder for method chaining.

Since: 1.0

Example:

UTIL_AsyncChain.newChain('MyChain')
    .then(new FirstStep())
    .then(new SecondStep())
    .execute();

then

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:

• step (IF_Chain.Step) - The IF_Chain.Step implementation to add.
• continueOnError (Boolean) - When true, the chain continues past this step's failure.

Returns: UTIL_AsyncChain.ChainBuilder - This ChainBuilder for method chaining.

Since: 1.0

Example:

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

withAsyncOptions

global UTIL_AsyncChain.ChainBuilder withAsyncOptions(AsyncOptions options)

Sets the AsyncOptions controlling queueable stack depth. When provided, these options override the framework default (maximumQueueableStackDepth = steps.size() + 1). In tests, pass options with an explicit maximumQueueableStackDepth matching the expected chain depth to enable chained Queueable execution within Test.startTest/stopTest.

Parameters:

• options (AsyncOptions) - The AsyncOptions to use for queueable enqueuing.

Returns: UTIL_AsyncChain.ChainBuilder - This ChainBuilder for method chaining.

Since: 1.0

Example:

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

withInitialContext

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

Seeds the chain context with an initial key-value pair before execution begins. This is additive — each call adds one key-value pair to the initial context map.

Parameters:

• key (String) - The context key.
• value (Object) - The context value.

Returns: UTIL_AsyncChain.ChainBuilder - This ChainBuilder for method chaining.

Since: 1.0

Example:

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

withMaxContextSize

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:

• maximumSize (Integer) - The maximum context size in characters.

Returns: UTIL_AsyncChain.ChainBuilder - This ChainBuilder for method chaining.

Since: 1.0

Example:

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

withMaxSteps

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:

• maximumSteps (Integer) - The maximum number of steps permitted.

Returns: UTIL_AsyncChain.ChainBuilder - This ChainBuilder for method chaining.

Since: 1.0

Example:

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