Skip to content

UTIL_AsyncChain ​

Class · Group: Async

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

apex
global inherited sharing class UTIL_AsyncChain

Lightweight async chain runner for sequencing jobs with shared state, error handling, and progress tracking. Delegates to existing async and logging infrastructure. Each step runs in a queueable job of its own; the comments in this class call one such job a hop.

Example

apex
UTIL_AsyncChain.newChain('DataMigration')
    .then(new LoadDataStep())
    .then(new TransformDataStep())
    .onError(new NotifyAdminStep())
    .execute();

Methods ​

MethodDescription
global static UTIL_AsyncChain.StepResult failed(Exception error)Creates a failed step result from an exception, using the exception message.
global static UTIL_AsyncChain.StepResult failed(String message)Creates a failed step result with a descriptive message.
global static UTIL_AsyncChain.StepResult failedPermanently(Exception error)Creates a permanently failed step result from an exception, for a caught failure the step knows will always happen again.
global static UTIL_AsyncChain.StepResult failedPermanently(String message)Creates a permanently failed step result from a message: a failure the step knows will happen again on every try (a failed validation, a rejected business rule, a client error that can never succeed when sent again), so the chain must not spend retry budget on it.
global static UTIL_AsyncChain.ChainStatus getChainStatus(Id chainExecutionId)Retrieves the current status of a chain execution as a typed ChainStatus value object.
global static Map<Id, UTIL_AsyncChain.ChainStatus> getChainStatuses(Set<Id> chainExecutionIds)Bulk version of getChainStatus.
global static Map<String, Object> getStatus(Id chainExecutionId)Retrieves the current status of a chain execution as a map of key-value pairs.
global static UTIL_AsyncChain.ChainBuilder newChain(String chainName)Creates a new chain builder for composing a sequence of async steps.
global static UTIL_AsyncChain.StepResult succeeded()Creates a successful step result with no message.
global static UTIL_AsyncChain.StepResult succeeded(String message)Creates a successful step result with a descriptive message.
global static UTIL_AsyncChain.StepResult succeeded(String message, Object data)Creates a successful step result with a message and data payload.

failed ​

apex
global static UTIL_AsyncChain.StepResult failed(Exception error)

Creates a failed step result from an exception, using the exception message.

Parameters

ParameterTypeDescription
errorExceptionThe exception that caused the failure.

Returns UTIL_AsyncChain.StepResult — A StepResult with success set to false, the exception message, and the exception reference.

Example

apex
try { riskyOperation(); }
catch(Exception error) { return UTIL_AsyncChain.failed(error); }
apex
global static UTIL_AsyncChain.StepResult failed(String message)

Creates a failed step result with a descriptive message.

Parameters

ParameterTypeDescription
messageStringA human-readable description of the failure.

Returns UTIL_AsyncChain.StepResult — A StepResult with success set to false and the provided message.

Example

apex
return UTIL_AsyncChain.failed('Required field is blank');

failedPermanently ​

apex
global static UTIL_AsyncChain.StepResult failedPermanently(Exception error)

Creates a permanently failed step result from an exception, for a caught failure the step knows will always happen again. The exception is kept on the result exactly as with failed(exception). The permanent flag also refuses any retry, and it wins over both the attempt budget and every exception filter.

Parameters

ParameterTypeDescription
errorExceptionThe exception that caused the failure that will always happen again.

Returns UTIL_AsyncChain.StepResult — A StepResult with success false, the exception message and reference, and the permanent flag set.

apex
global static UTIL_AsyncChain.StepResult failedPermanently(String message)

Creates a permanently failed step result from a message: a failure the step knows will happen again on every try (a failed validation, a rejected business rule, a client error that can never succeed when sent again), so the chain must not spend retry budget on it. The retry strategy is never asked, the chain fails on this attempt, and FailureCategory__c records StepException.

Parameters

ParameterTypeDescription
messageStringA human-readable description of the failure that will always happen again.

Returns UTIL_AsyncChain.StepResult — A StepResult with success false, the provided message, and the permanent flag set.

Example

apex
return UTIL_AsyncChain.failedPermanently('Order was cancelled upstream');

getChainStatus ​

apex
global static UTIL_AsyncChain.ChainStatus getChainStatus(Id chainExecutionId)

Retrieves the current status of a chain execution as a typed ChainStatus value object. It is the structured alternative to the untyped getStatus(Id) map. ChainStatus exposes every tracked field (chain name, status, current step, correlation ID, step counts, error message, timing) plus the helper checks isRunning(), isTerminal() and isFailed().

It reads through the same selector as getStatus(Id), which respects sharing: a caller only sees chains they have access to. To see every chain in the org, use the Chain Monitor console instead. For detail on each step, use the Chain Monitor. ChainStatus is a summary of one record and has no step list on purpose.

Parameters

ParameterTypeDescription
chainExecutionIdIdThe ID of the AsyncChainExecution__c record to query.

Returns UTIL_AsyncChain.ChainStatus — A ChainStatus describing the execution, or null if the record is not found or not visible.

Example

apex
UTIL_AsyncChain.ChainStatus status = UTIL_AsyncChain.getChainStatus(executionId);
if(status != null && status.isFailed())
{
    String reason = status.errorMessage;
}

getChainStatuses ​

apex
global static Map<Id, UTIL_AsyncChain.ChainStatus> getChainStatuses(Set<Id> chainExecutionIds)

Bulk version of getChainStatus. It turns a set of execution IDs into ChainStatus objects with a single query, so it does not use up the query limit when many IDs are needed. IDs that do not match a visible record are simply left out of the returned map. It uses the same selector as getChainStatus, which respects sharing, so a caller only sees chains they can access.

Parameters

ParameterTypeDescription
chainExecutionIdsSetThe IDs of the AsyncChainExecution__c records to query.

Returns UTIL_AsyncChain.ChainStatus — A map of execution ID to ChainStatus for every record found; empty when nothing resolves.

Example

apex
Map<Id, UTIL_AsyncChain.ChainStatus> statuses = UTIL_AsyncChain.getChainStatuses(executionIds);

getStatus ​

apex
global static Map<String, Object> getStatus(Id chainExecutionId)

Retrieves the current status of a chain execution as a map of key-value pairs.

Parameters

ParameterTypeDescription
chainExecutionIdIdThe ID of the AsyncChainExecution__c record to query.

Returns Object — A map containing executionId, chainName, status, totalSteps, completedSteps, and errorMessage. Returns null if the record is not found.

Example

apex
Map<String, Object> status = UTIL_AsyncChain.getStatus(executionId);
String currentStatus = (String)status.get('status');

newChain ​

apex
global static UTIL_AsyncChain.ChainBuilder newChain(String chainName)

Creates a new chain builder for composing a sequence of async steps.

Parameters

ParameterTypeDescription
chainNameStringA descriptive name for the chain, used in logs and status tracking.

Returns UTIL_AsyncChain.ChainBuilder — A new ChainBuilder instance for fluent configuration.

Example

apex
UTIL_AsyncChain.ChainBuilder builder = UTIL_AsyncChain.newChain('DataMigration');

succeeded ​

apex
global static UTIL_AsyncChain.StepResult succeeded()

Creates a successful step result with no message.

Returns UTIL_AsyncChain.StepResult — A StepResult with success set to true.

Example

apex
return UTIL_AsyncChain.succeeded();
apex
global static UTIL_AsyncChain.StepResult succeeded(String message)

Creates a successful step result with a descriptive message.

Parameters

ParameterTypeDescription
messageStringA human-readable description of the successful outcome.

Returns UTIL_AsyncChain.StepResult — A StepResult with success set to true and the provided message.

Example

apex
return UTIL_AsyncChain.succeeded('Processed 42 records');
apex
global static UTIL_AsyncChain.StepResult succeeded(String message, Object data)

Creates a successful step result with a message and data payload. The data is serialized into the chain context between transactions, so keep it small: use record IDs or primitive values, not full SObject graphs or large collections.

Parameters

ParameterTypeDescription
messageStringA human-readable description of the successful outcome.
dataObjectArbitrary data to pass to subsequent steps via the context. Prefer IDs and primitives.

Returns UTIL_AsyncChain.StepResult — A StepResult with success set to true, the provided message, and data.

Example

apex
List<Id> processedIds = new List<Id>{ record.Id };
return UTIL_AsyncChain.succeeded('Processed records', processedIds);

Inner Classes ​

ClassDescription
ApiStepChain step adapter that executes any API_Outbound handler as part of an async chain.
ChainBuilderFluent builder for configuring and executing an async chain.
ChainContextShared state container passed between chain steps.
ChainStatusTyped, read-only snapshot of a chain execution returned by getChainStatus.
ChainStepAbstract base class for individual steps in an async chain.
StepResultImmutable result object returned by each ChainStep to indicate success or failure.