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.

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

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.

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

Developers can, instead, programatically 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(state: AdaptableState, config: UpgradeConfig): AdaptableState

As can be seen it takes 2 properties (some AdaptableState, and an UpgradeConfig Object) and returns the updated State.

The UpgradeConfig object allows you to define which versions to upgrade and provide a custom logger if needed:

Property	Description	Default
fromVersion	AdapTable version to upgrade from
logger	The logger object	The console object
toVersion	AdapTable version to upgrade to	The current version

So to perform a custom migration between specific versions - in this example from Version 20 to Version 21 - and additionally modify state properties, add custom properties, or remove existing ones would be:

stateOptions: {
    autoMigrateState: false,
    applyState: (state: AdaptableState) => {
      const config: UpgradeConfig = {
        fromVersion: 20,
        toVersion: 21,
      };
      const v21_state = AdaptableUpgradeHelper.migrateAdaptableState(state, config);  
      // perform additional, custom/application specific state migration here
      return v21_state;
    }
}

Hint

See the full guide to Persisting State for more details on how the applyState function works

PreviousListening to AdapTable State NextTechnical Reference

Framework: