# State Migration Tool

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

- Paste AdapTable State for one major version and migrate it to another
- The same page runs inside AdapTable DevTools against the Grid you are inspecting
- State is migrated in memory and is not stored

The State Migration Tool runs `AdaptableUpgradeHelper.migrateAdaptableState` on a server.

This allows you to read the migrated State and the migration log **before** changing the application. 

See [Migrating AdapTable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-migrating-state/index.md) for full details on this topic

## Panels

The State Migration Tool contains 2 panels:

### Source Panel (Left)

The left panel is the source of the State.

Choose the major version the State was saved with and paste the State as JSON or JSON5.

Comments, trailing commas, single quotes, and unquoted keys are all allowed.

AdapTable version 16 is the oldest version the migration tool supports 

### Target Panel (Right)

The right panel is the target.

Choose the major version to migrate to, and the format of the result. 

- JSON is the default choice
- JSONC adds trailing commas
- JSON5 uses unquoted keys where it can

That choice is sent as `format` on `POST /migrate`, and the response body is written in the same format. 

**Show diff** compares the source with the migrated State in that format. 

The target list is every major this server can produce, up to the version it was built with.

The hosted server is [https://state-migration.adaptabletools.com](https://state-migration.adaptabletools.com)

- You can run the same migration in your own Node process if you wish
- Simply import `AdaptableUpgradeHelper` from `@adaptabletools/adaptable/upgrade`

## From the command line

The [adaptable CLI](https://www.adaptabletools.com/docs/getting-started-ai-cli/index.md) runs the same migration locally, on an exported State or straight on the `initialState` literal in a source file, and reports the leftovers it could not convert with their positions:

<AiCli args="migrate state src/adaptableOptions.ts --from 23 --to 24 --out migrated.json" />

This is what the [adaptable-upgrade](https://www.adaptabletools.com/docs/getting-started-ai-skills-upgrade/index.md) Agent Skill uses to write `ADAPTABLE_UPGRADE_STATE/` in an upgrade plan; `check state` on the result then validates it against the target version's types.

## In DevTools

The [AdapTable DevTools](https://www.adaptabletools.com/docs/dev-guide-support-devtools/index.md) **Migrate** tab opens this page in live mode.

The source version and State are taken from the Grid that the user is currently inspecting.

The state taken is the persistent State, without the transient `Internal`, `Popup`, `Comment` and `Plugins` sections

Choose the target version on the right — usually the next major — and use **Restore to grid** to load the migrated State back into that instance.

- [Migrating AdapTable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-migrating-state/index.md)
- [AdapTable DevTools](https://www.adaptabletools.com/docs/dev-guide-support-devtools/index.md)
- [Hosted server](https://state-migration.adaptabletools.com)