UTIL_AsyncChain

Class · Group: Async

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.

Example

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

---

Methods

Method	Description
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.ChainStatus getChainStatus(Id chainExecutionId)	Retrieves the current status of a chain execution as a typed ChainStatus value object — the structured alternative to the untyped getStatus(Id) map.
global static Map<Id, UTIL_AsyncChain.ChainStatus> getChainStatuses(Set<Id> chainExecutionIds)	Bulk variant of getChainStatus — resolves a set of execution IDs to ChainStatus objects in a single query, so it is safe to call from within a loop budget.
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

global static UTIL_AsyncChain.StepResult failed(Exception error)

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

Parameters

Parameter	Type	Description
error	Exception	The exception that caused the failure.

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

Example

try { riskyOperation(); }
catch(Exception error) { return UTIL_AsyncChain.failed(error); }

global static UTIL_AsyncChain.StepResult failed(String message)

Creates a failed step result with a descriptive message.

Parameters

Parameter	Type	Description
message	String	A human-readable description of the failure.

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

Example

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

getChainStatus

global static UTIL_AsyncChain.ChainStatus getChainStatus(Id chainExecutionId)

Retrieves the current status of a chain execution as a typed ChainStatus value object — 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 convenience predicates isRunning(), isTerminal() and isFailed().

Reads through the same sharing-respecting selector path as getStatus(Id): a caller only sees chains they have access to. For an org-wide observability view of every chain, use the Chain Monitor console instead. For per-step detail, parse the Chain Monitor's step DTOs — ChainStatus is a single-record summary and intentionally carries no step list.

Parameters

Parameter	Type	Description
chainExecutionId	Id	The 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

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

getChainStatuses

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

Bulk variant of getChainStatus — resolves a set of execution IDs to ChainStatus objects in a single query, so it is safe to call from within a loop budget. IDs that do not resolve to a visible record are simply absent from the returned map. Uses the same sharing-respecting selector path as getChainStatus, so a caller only sees chains they can access.

Parameters

Parameter	Type	Description
chainExecutionIds	Set	The 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

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

getStatus

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

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

Parameters

Parameter	Type	Description
chainExecutionId	Id	The 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

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

newChain

global static UTIL_AsyncChain.ChainBuilder newChain(String chainName)

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

Parameters

Parameter	Type	Description
chainName	String	A descriptive name for the chain, used in logs and status tracking.

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

Example

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

succeeded

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

return UTIL_AsyncChain.succeeded();

global static UTIL_AsyncChain.StepResult succeeded(String message)

Creates a successful step result with a descriptive message.

Parameters

Parameter	Type	Description
message	String	A human-readable description of the successful outcome.

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

Example

return UTIL_AsyncChain.succeeded('Processed 42 records');

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

Parameter	Type	Description
message	String	A human-readable description of the successful outcome.
data	Object	Arbitrary 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

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

Inner Classes

Class	Description
ApiStep	Chain step adapter that executes any API_Outbound handler as part of an async chain.
ChainBuilder	Fluent builder for configuring and executing an async chain.
ChainContext	Shared state container passed between chain steps.
ChainStatus	Typed, read-only snapshot of a chain execution returned by getChainStatus.
ChainStep	Abstract base class for individual steps in an async chain.
StepResult	Immutable result object returned by each ChainStep to indicate success or failure.

---