# UTIL_AsyncChain.ChainContext

**Class** · Group: `Async`

Learn it: [Fast Start - Async Processing](/fast-start-async-processing) and [Async Processing guide](/async-processing-guide)

<div class="apex-member apex-class">

```apex
global inherited sharing class UTIL_AsyncChain.ChainContext
```

Shared state container passed between chain steps. Provides key-value storage for inter-step communication and access to chain metadata such as execution ID and correlation ID.

**Example**

```apex
context.put('accountId', account.Id);
Id accountId = (Id)context.get('accountId');
Boolean hasKey = context.has('accountId');
```

</div>

---

## Methods

| Method | Description |
|--------|-------------|
| global [Object](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_System_Object.htm) [get](#get)([String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) key) | Retrieves a value from the context by key. |
| global [Object](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_System_Object.htm) [getAs](#getas)([String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) key, [Type](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_type.htm) targetType) | Retrieves a value from the context and deserializes it to the specified type. |
| global [Integer](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_integer.htm) [getAttempt](#getattempt)() | The 1-based attempt number of the currently executing step. |
| global [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) [getChainExecutionId](#getchainexecutionid)() | Returns the ID of the AsyncChainExecution__c record tracking this chain. |
| global [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) [getCorrelationId](#getcorrelationid)() | Returns the correlation ID for this chain, used for log correlation across transactions. |
| global [Integer](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_integer.htm) [getCurrentStepIndex](#getcurrentstepindex)() | Returns the zero-based index of the currently executing step. |
| global [UTIL_AsyncChain.StepResult](/reference/apex/util-asyncchain-stepresult) [getPreviousStepResult](#getpreviousstepresult)() | Returns the result of the most recently completed step. |
| global [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) [has](#has)([String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) key) | Checks whether the context contains a value for the given key. |
| global [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) [idempotencyKey](#idempotencykey)() | Returns the step-level idempotency key for the currently executing step: the chain execution id joined to the step index. |
| global [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) [idempotencyKey](#idempotencykey)([Id](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_id.htm) recordId) | Returns the per-record idempotency key for a step that works through many records: the step-level key joined to the given record id. |
| global [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) [idempotencyKey](#idempotencykey)([String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) grain) | Returns a custom idempotency key for a step that works through units that are not records (for example line numbers or external keys): the step-level key joined to the given grain, the value that names one unit. |
| global [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) [isFinalAttempt](#isfinalattempt)() | True when no further retry remains for the currently executing step, judged by the strategy's attempt budget alone. |
| global [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) [isFinalAttempt](#isfinalattempt)([Exception](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_exception_methods.htm) error) | True when failing the current attempt with the given exception would be final. |
| global void [put](#put)([String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) key, [Object](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_System_Object.htm) value) | Stores a value in the context under the given key. |

### get

<div class="apex-member">

```apex
global Object get(String key)
```

Retrieves a value from the context by key.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) | The key to look up. |

**Returns** [Object](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_System_Object.htm) — The stored value, or null if not found.

**Example**

```apex
Object value = context.get('recordCount');
```

</div>

### getAs

<div class="apex-member">

```apex
global Object getAs(String key, Type targetType)
```

Retrieves a value from the context and deserializes it to the specified type.
Useful for retrieving complex objects that were stored via put() and serialized between transactions.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) | The key to look up. |
| `targetType` | [Type](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_type.htm) | The Apex Type to deserialize the value into. |

**Returns** [Object](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_System_Object.htm) — The deserialized value, or null if the key is not found.

**Example**

```apex
List<String> names = (List<String>)context.getAs('nameList', List<String>.class);
```

</div>

### getAttempt

<div class="apex-member">

```apex
global Integer getAttempt()
```

The 1-based attempt number of the currently executing step. 1 on the first
attempt and for every step without a retry strategy; increments per retry.

**Returns** [Integer](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_integer.htm) — The 1-based attempt number of the currently executing step.

</div>

### getChainExecutionId

<div class="apex-member">

```apex
global String getChainExecutionId()
```

Returns the ID of the AsyncChainExecution__c record tracking this chain.

**Returns** [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) — The chain execution record ID.

**Example**

```apex
String executionId = context.getChainExecutionId();
```

</div>

### getCorrelationId

<div class="apex-member">

```apex
global String getCorrelationId()
```

Returns the correlation ID for this chain, used for log correlation across transactions.

**Returns** [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) — The correlation ID string.

**Example**

```apex
String correlationId = context.getCorrelationId();
```

</div>

### getCurrentStepIndex

<div class="apex-member">

```apex
global Integer getCurrentStepIndex()
```

Returns the zero-based index of the currently executing step.
To build a replay-safe key for this step, call context.idempotencyKey() rather than composing
the execution id and step index by hand.

**Returns** [Integer](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_integer.htm) — The current step index, or null for contexts not yet assigned to a step.

**Example**

```apex
String key = context.idempotencyKey();
String rowKey = context.idempotencyKey(recordId);
```

</div>

### getPreviousStepResult

<div class="apex-member">

```apex
global UTIL_AsyncChain.StepResult getPreviousStepResult()
```

Returns the result of the most recently completed step. Returns null for the first step.

**Returns** [UTIL_AsyncChain.StepResult](/reference/apex/util-asyncchain-stepresult) — The previous step's StepResult, or null if this is the first step.

**Example**

```apex
UTIL_AsyncChain.StepResult previous = context.getPreviousStepResult();
if(previous != null && previous.success)
{
    String message = previous.message;
}
```

</div>

### has

<div class="apex-member">

```apex
global Boolean has(String key)
```

Checks whether the context contains a value for the given key.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) | The key to check. |

**Returns** [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) — True if the key exists in the context, false otherwise.

**Example**

```apex
if(context.has('accountId'))
{
    Id accountId = (Id)context.get('accountId');
}
```

</div>

### idempotencyKey

<div class="apex-member">

```apex
global String idempotencyKey()
```

Returns the step-level idempotency key for the currently executing step: the
chain execution id joined to the step index. The key stays identical when the same step
replays, so a step that does one logical unit of work can store this key on an external-id
field and upsert (a replay updates the same record instead of creating a duplicate), or write
it to a marker for a side effect that cannot be upserted (a callout, an email) and skip when
the marker is already present. Treat the result as an opaque token: compare it or store it
whole, and do not split it to read back the run or step (use getChainExecutionId() and
getCurrentStepIndex() for those). Call it from within a step's work(context), where the step
index is always assigned.

**Returns** [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) — The step-level key, the execution id + "-" + step index.

**Example**

```apex
String key = context.idempotencyKey();
```

</div>

<div class="apex-member">

```apex
global String idempotencyKey(Id recordId)
```

Returns the per-record idempotency key for a step that works through many
records: the step-level key joined to the given record id. Use it so a replay after a
partial failure only reprocesses the rows that did not complete the first time, instead of
re-running or skipping the whole step. A null recordId falls back to the bare step-level key.
An 18-character Id keeps the whole key well under the 255-character external-id limit, so this
overload needs no length caveat. Treat the result as an opaque token. Pass a literal null as a
typed variable or a cast ((Id) null), because a bare idempotencyKey(null) is ambiguous between
this overload and the String overload.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `recordId` | [Id](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_id.htm) | The record being processed, which makes the key unique per record. |

**Returns** [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) — The step-level key + "-" + recordId, or the bare step-level key when recordId is null.

**Example**

```apex
String rowKey = context.idempotencyKey(record.Id);
```

</div>

<div class="apex-member">

```apex
global String idempotencyKey(String grain)
```

Returns a custom idempotency key for a step that works through units that are
not records (for example line numbers or external keys): the step-level key joined to the
given grain, the value that names one unit. A null or blank grain falls back to the bare
step-level key. The grain passes through verbatim, so the helper never hashes or truncates it.
The composed key is typically stored on a Text external-id field capped at 255 characters; an
over-long key fails loudly at upsert with a STRING_TOO_LONG DmlException (not silent
truncation), so it surfaces in your own test. If you need a long composite grain, shorten it
yourself (a one-line hash of just the grain) before passing it. Treat the result as an opaque
token. Pass a literal null as a typed variable or a cast ((String) null), because a bare
idempotencyKey(null) is ambiguous between this overload and the Id overload.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `grain` | [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) | A short value that names one unit of the step's work and does not change between attempts. |

**Returns** [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) — The step-level key + "-" + grain, or the bare step-level key when grain is blank.

**Example**

```apex
String lineKey = context.idempotencyKey('orderLine-' + lineNumber);
```

</div>

### isFinalAttempt

<div class="apex-member">

```apex
global Boolean isFinalAttempt()
```

True when no further retry remains for the currently executing step, judged
by the strategy's attempt budget alone. The value is set before work() runs, so it cannot
know which exception the attempt will fail with. A strategy wrapped in an exception filter
can still refuse the retry afterwards. When that happens, the framework corrects the value
before it passes the failure on, so an onError handler always reads true for a failure
that was final. To ask "would failing with THIS exception be final?" from inside work(),
use isFinalAttempt(error).

**Returns** [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) — True when a failure of the current attempt is final; false when a retry remains.

</div>

<div class="apex-member">

```apex
global Boolean isFinalAttempt(Exception error)
```

True when failing the current attempt with the given exception would be
final. Unlike isFinalAttempt(), which reads the attempt budget alone and cannot know
that an exception filter would refuse the retry, this overload asks the current
step's full strategy, filters included, with the exception you are about to fail with.
Call it from inside work(), before returning or throwing, when a last-chance side
effect (release a lock, write a marker, alert someone) must run exactly when no retry
will follow. Outside work(), for example in an onError handler, there is no strategy and
the method returns true. That is correct there: a failure passed to the handler is final.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `error` | [Exception](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_exception_methods.htm) | The exception the step is about to fail with, or null for a message-only failure. |

**Returns** [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) — True when a failure with this exception ends the step's attempts.

**Example**

```apex
if(context.isFinalAttempt(caught)) { releaseLock(); }
return UTIL_AsyncChain.failed(caught);
```

</div>

### put

<div class="apex-member">

```apex
global void put(String key, Object value)
```

Stores a value in the context under the given key.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) | The key to store the value under. |
| `value` | [Object](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_System_Object.htm) | The value to store. |

**Example**

```apex
context.put('batchSize', 200);
```

</div>
