Migrating Adaptable State
Summary
- 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.
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.
Hint
- 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:
- Detects outdated Adaptable State
- Performs necessary updates and conversions
- 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.setAdaptableStateKeyandstateApi.loadUserStatestateApi.applyInitialStateandstateApi.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.
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 to false.
autoMigrateState
Default: trueBooleanDevelopers can, instead, programmatically upgrade their AdapTable State at any time, by calling the static AdaptableUpgradeHelper.migrateAdaptableState function.
Deep Dive
Guide to Migrating State Manually
The static migrateAdaptableState function in AdaptableUpgradeHelper is defined as follows:
static migrateAdaptableState<T extends Partial<AdaptablePersistentState>>(state: T, config: UpgradeConfig): TAs 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 object allows you to define which versions to upgrade and provide a custom logger if needed:
Config object used by State Auto-migration Wizard
| Property | Type | Description | Default |
|---|---|---|---|
| fromVersion | number | AdapTable version to upgrade from | |
| layoutTagOptions | LayoutTagOptions | Layout Tag Options in use before upgrading; when autoCheckTagsForLayouts is true, Tags whichmatch Layout names are converted into the Layout Extensions registry (v24) | |
| logger | MigrationLogger | The logger object | The console object |
| 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, then apply any extra application-specific adjustments:
stateOptions: {
autoMigrateState: false,
applyState: (state) => {
const migrated = AdaptableUpgradeHelper.migrateAdaptableState(state, {
fromVersion: 23,
toVersion: 24,
});
// perform additional, custom/application specific state migration here
return migrated;
}
}Hint
See the full guide to Persisting State 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, or migrate the Grid you are inspecting from the DevTools Migrate tab.
import { AdaptableUpgradeHelper } from '@adaptabletools/adaptable/upgrade';
const migrated = AdaptableUpgradeHelper.migrateAdaptableState(savedState, {
fromVersion: 23,
});