Skip to content

UTIL_AsyncChain.ChainStatus ​

Class · Group: Async

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

apex
global inherited sharing class UTIL_AsyncChain.ChainStatus

Typed, read-only snapshot of a chain execution returned by getChainStatus. A structured alternative to the getStatus(Id) map: each tracked field is a named property and the lifecycle can be checked through isRunning(), isTerminal() and isFailed(). It holds no step list and runs no queries: it is a plain value object built from a single AsyncChainExecution__c row.

Example

apex
UTIL_AsyncChain.ChainStatus status = UTIL_AsyncChain.getChainStatus(executionId);
Boolean stillRunning = status.isRunning();
Integer done = status.completedSteps;

Methods ​

MethodDescription
global Boolean isFailed()True only for the Failed status.
global Boolean isRunning()Whether the chain is currently running.
global Boolean isTerminal()Whether the chain has reached a terminal state, from which it will not move on: Completed, Failed or Aborted, or any row with a completion timestamp.

isFailed ​

apex
global Boolean isFailed()

True only for the Failed status. An Aborted chain returns false, so use isTerminal to learn whether the chain has ended for any reason. A Stalled chain also returns false: it has not ended, it is waiting for recovery. errorMessage holds the reason for the failure.

Returns Boolean — true when the status is Failed.

Example

apex
if(status.isFailed()) { escalate(status.errorMessage); }

isRunning ​

apex
global Boolean isRunning()

Whether the chain is currently running. A Stalled chain reports as neither running nor terminal: it is waiting for recovery after a temporary platform limit stopped the framework from scheduling its next piece of work, or after the SCHED_ChainWatchdog scheduled job found it silently stuck. The reserved Delayed status, which the framework does not currently write, is reported the same way.

Returns Boolean — true when the status is Running.

Example

apex
if(status.isRunning()) { return; }

isTerminal ​

apex
global Boolean isTerminal()

Whether the chain has reached a terminal state, from which it will not move on: Completed, Failed or Aborted, or any row with a completion timestamp. The timestamp check covers a rare recovery write that can leave a finished chain showing Stalled. The completion timestamp is kept through that write, so it is the reliable sign that the chain has ended.

Returns Boolean — true when the status is Completed, Failed or Aborted, or completedAt is set.

Example

apex
if(status.isTerminal()) { notifyDone(status); }

Fields ​

FieldDescription
global String chainNameThe descriptive chain name supplied to newChain(...).
global Datetime completedAtWhen the chain reached a terminal state; null while it is still running.
global Integer completedStepsThe number of steps completed so far.
global String correlationIdThe correlation ID that ties this chain's log entries together.
global String currentStepNameThe name of the step currently executing (or last executed), if recorded.
global String durationLabelA compact, human-readable form of durationMs (for example "1m 30s"); null when no duration is available.
global Long durationMsElapsed run time in milliseconds, the same value the Chain Monitor console shows.
global String errorMessageThe failure message, when the chain has failed; otherwise null.
global Id executionIdThe AsyncChainExecution__c record ID.
global Datetime startedAtWhen the chain started executing.
global String statusThe lifecycle status: one of Running, Completed, Failed, Stalled or Aborted.
global Integer totalStepsThe total number of steps in the chain.

chainName ​

apex
global String chainName

Type: String

The descriptive chain name supplied to newChain(...).

completedAt ​

apex
global Datetime completedAt

Type: Datetime

When the chain reached a terminal state; null while it is still running.

completedSteps ​

apex
global Integer completedSteps

Type: Integer

The number of steps completed so far.

correlationId ​

apex
global String correlationId

Type: String

The correlation ID that ties this chain's log entries together.

currentStepName ​

apex
global String currentStepName

Type: String

The name of the step currently executing (or last executed), if recorded.

durationLabel ​

apex
global String durationLabel

Type: String

A compact, human-readable form of durationMs (for example "1m 30s"); null when no duration is available.

durationMs ​

apex
global Long durationMs

Type: Long

Elapsed run time in milliseconds, the same value the Chain Monitor console shows. A finished chain reports the duration it stored. A chain that is still Running, or has Stalled, reports how long it has been going since startedAt. A Completed, Failed or Aborted chain that stored no duration reports the time between startedAt and completedAt. Null when no duration can be worked out, for example for a chain that recorded no start.

errorMessage ​

apex
global String errorMessage

Type: String

The failure message, when the chain has failed; otherwise null.

executionId ​

apex
global Id executionId

Type: Id

The AsyncChainExecution__c record ID.

startedAt ​

apex
global Datetime startedAt

Type: Datetime

When the chain started executing.

status ​

apex
global String status

Type: String

The lifecycle status: one of Running, Completed, Failed, Stalled or Aborted. The framework writes Stalled when a temporary platform limit stops it from scheduling the chain's next piece of work: the chain waits for recovery instead of failing. The SCHED_ChainWatchdog scheduled job also writes Stalled when its sweep finds a chain silently stuck with no recent activity. (The picklist also defines Delayed, which the framework does not currently write.) Prefer the isRunning()/isTerminal()/isFailed() checks over comparing this String. If the status is Stalled but completedAt is set, a recovery write changed a chain that had already finished. isTerminal() reports such a row as terminal.

totalSteps ​

apex
global Integer totalSteps

Type: Integer

The total number of steps in the chain.