# Migrating to Activix v5 (`runContext`)

Activix **v5** uses **`runContext`** as the default BSON field name and the primary property on write APIs for the per-run correlation object (formerly default **`identity`**).

After you rename symbols, point teammates at **[run-context-object.md](./run-context-object.md)** so the mental model (config vs caller identity vs run context) is clear.

## No `identity` left in the default API

For default configuration, **`identity`**, **`identityField`**, **`findRecordsByIdentity`**, and **`FindByIdentityCriteria`** are **removed**—not deprecated with aliases. Your code and Mongo paths must move to **`runContext`** / **`runContextField`** / **`findRecordsByRunContext`** / **`FindByRunContextCriteria`**, or you must opt into the legacy BSON key with **`runContextField: 'identity'`** (and then pass **`identity:`** on payloads until you rename documents). See also [run-context-object.md § v5 runContext-only API (quick)](./run-context-object.md#v5-runcontext-only-api-quick).

## Renames

| Before (v4) | After (v5) |
|-------------|------------|
| Default BSON field `identity` | Default BSON field `runContext` |
| `identityField` (collection config) | `runContextField` |
| `startRecord({ identity: … })` | `startRecord({ runContext: … })` |
| `findRecordsByIdentity` | `findRecordsByRunContext` |
| Criteria property `identity` | `runContext` |
| `FindByIdentityCriteria` | `FindByRunContextCriteria` |
| Persistence helpers option `identityField` | `runContextField` |

## Code updates

- Replace every **`identity`** payload key with **`runContext`** unless you use a custom field name (below).
- Update **`findRecords`** raw filters: e.g. `'identity.sessionId'` → `'runContext.sessionId'`.
- Update Mongo **indexes** that targeted `identity.*` to `runContext.*` (or your configured `runContextField`).

## Existing MongoDB documents

**Option A — rename the field** (typical for greenfield or batch migration):

```js
// Example; use your real collection name and test on a backup first.
db.yourActivities.updateMany({}, { $rename: { identity: 'runContext' } })
```

Then recreate or adjust indexes (e.g. `identity.sessionId` → `runContext.sessionId`).

**Option B — keep BSON key `identity` for a while:** set on the collection config:

```ts
runContextField: 'identity'
```

Activix will read and write the nested object under **`identity`** in Mongo. On **`startRecord`** / updates, pass that object under the **same key** as the field name — i.e. **`identity: { … }`** while `runContextField` is `'identity'`. When you finish migrating documents, remove `runContextField` (default `runContext`) and switch payloads to **`runContext`**.

## Type export

**`ActivixRunContext`** remains the TypeScript name for the object’s shape; it is not tied to the old **`identity`** key.