Migrating Adaptable State

View as Markdown

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:

  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.

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: true
Boolean
Automatically migrates Adaptable State between Old and New Versions

Developers 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): 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 object allows you to define which versions to upgrade and provide a custom logger if needed:

Config object used by State Auto-migration Wizard

PropertyTypeDescriptionDefault
fromVersionnumberAdapTable version to upgrade from
layoutTagOptionsLayoutTagOptionsLayout Tag Options in use before upgrading; when autoCheckTagsForLayouts is true, Tags which
match Layout names are converted into the Layout Extensions registry (v24)
loggerMigrationLoggerThe logger objectThe console object
toVersionnumberAdapTable version to upgrade toThe 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,
});