# Migrating Adaptable State

Canonical page: https://www.adaptabletools.com/docs/dev-guide-adaptable-state-migrating-state

- AdapTable provides an automated State Upgrade Process to manage the transitions from different version of State
- This is particularly useful when a major version has introduced breaking changes
- Users can opt out from this and choose manually to upgrade their state.

We try hard to ensure that all changes to the `InitialState` object are fully backwardly compatible.  

However, very occasionally, the implementation of an enhancement request, requires an update to Initial State that introduces a **breaking change**.

Initial State related breaking changes only happen once a year at most, and only in a Major Version release

## Automatic State Migration

AdapTable includes an automated State Upgrade Process that seamlessly converts any existing **_old_** Adaptable State to the **_new_** AdapTable State format.

- This upgrade process runs silently in the background each time AdapTable starts
- However, its effects are most significant when the application loads for the first time after a major version update

The upgrade process operates automatically without any user intervention:
1. Detects outdated Adaptable State
2. Performs necessary updates and conversions
3. Saves the updated State for future use

Users will experience no disruption as all migrations happen transparently in the background.

The same upgrade runs in each of these places when `autoMigrateState` is `true`:

- grid startup
- `stateApi.setAdaptableStateKey` and `stateApi.loadUserState`
- `stateApi.applyInitialState` and `stateApi.remergePersistedState`
- a DevTools state restore
- Team Sharing, when shared entities are loaded

`stateOptions.applyState` runs before the upgrade on startup and when the state key changes. `teamSharingOptions.applySharedEntities` runs after shared entities have been migrated.

`teamSharingOptions.persistMigratedSharedEntities` (default `true`) writes those migrated shared entities back once per grid session for a user with full Team Sharing rights. The write does not change `Revision` or `ChangedAt`. See [Setting up Team Sharing](https://www.adaptabletools.com/docs/handbook-team-sharing-configuring/index.md#migrating-shared-entities).

## Manual State Migration

Developers can choose to handle state migrations manually by disabling the automatic process.

This is done by setting `autoMigrateState` in [State Options](https://www.adaptabletools.com/docs/technical-reference-adaptable-state/index.md) to *false*.

### `autoMigrateState`

Automatically migrates Adaptable State between Old and New Versions

This property decides whether AdapTable automatically updates the AdapTable State between major versions.

This ensures that all breaking changes are dealt with in a way that is hidden from the user.

Developer can choose to update State manually by setting this property to *false*.

```ts {3}
const adaptableOptions: AdaptableOptions = {
  stateOptions: {
    autoMigrateState: false
  },
};
```

Developers can, instead, programmatically upgrade their AdapTable State at any time, by calling the static `AdaptableUpgradeHelper.migrateAdaptableState` function.

### Guide to Migrating State Manually

The static `migrateAdaptableState` function in `AdaptableUpgradeHelper` is defined as follows:

```ts
static migrateAdaptableState<T extends Partial<AdaptablePersistentState>>(state: T, config: UpgradeConfig): T
```

As can be seen it takes 2 properties (some Adaptable State - either the full `AdaptableState` or the (partial) `AdaptablePersistentState` received in `applyState`, and an `UpgradeConfig` Object) and returns the updated State, in the same shape it was given.

The [`UpgradeConfig`](https://www.adaptabletools.com/docs/reference/upgradeconfig.md) object allows you to define which versions to upgrade and provide a custom logger if needed:

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [fromVersion](https://www.adaptabletools.com/docs/reference/upgradeconfig.md#fromversion) | `number` | AdapTable version to upgrade from |   |
| [layoutTagOptions](https://www.adaptabletools.com/docs/reference/upgradeconfig.md#layouttagoptions) | [`LayoutTagOptions`](https://www.adaptabletools.com/docs/reference/layouttagoptions.md) | Layout Tag Options in use before upgrading; when `autoCheckTagsForLayouts` is true, Tags which<br/>match Layout names are converted into the Layout Extensions registry (v24) |   |
| [logger](https://www.adaptabletools.com/docs/reference/upgradeconfig.md#logger) | `MigrationLogger` | The logger object | The console object |
| [toVersion](https://www.adaptabletools.com/docs/reference/upgradeconfig.md#toversion) | `number` | AdapTable version to upgrade to | The current version |

Call it from `applyState` when you have turned automatic migration off. Pass the `fromVersion` / `toVersion` pair listed in the current [Release Note](https://www.adaptabletools.com/support/version-240-release-note), then apply any extra application-specific adjustments:

```ts {2,8}
stateOptions: {
    autoMigrateState: false,
    applyState: (state) => {
      const migrated = AdaptableUpgradeHelper.migrateAdaptableState(state, {
        fromVersion: 23,
        toVersion: 24,
      });
      // perform additional, custom/application specific state migration here
      return migrated;
    }
}
```

See the full guide to [Persisting State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-persistence/index.md#applystate) for more details on how the `applyState` function works

To migrate State outside the browser (e.g. in a Node script or on a server), import the helper from the `@adaptabletools/adaptable/upgrade` entry, which has no UI or AG Grid code.

You can also paste State into the [State Migration Tool](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-migration-tool/index.md), or migrate the Grid you are inspecting from the DevTools **Migrate** tab.

```ts
import { AdaptableUpgradeHelper } from '@adaptabletools/adaptable/upgrade';

const migrated = AdaptableUpgradeHelper.migrateAdaptableState(savedState, {
  fromVersion: 23,
});
```
