# Configuring Data Change History

Canonical page: https://www.adaptabletools.com/docs/handbook-monitoring-data-change-history-configuring

- Set how Data Change History works and what is tracked

Data Change History is configured in `dataChangeHistoryOptions` on [Adaptable Options](https://www.adaptabletools.com/docs/technical-reference-adaptable-options/index.md):

| Property                 | Section on this page           |
| ------------------------ | ------------------------------ |
| `activeByDefault`        | Making Active by Default       |
| `showDataChange`         | Limiting Data Changes          |
| `showLastDataChangeOnly` | Show All Data Changes          |
| `maxDataChangesInStore`  | Limiting Data Changes in Store |

- See [Data Change History Buttons](https://www.adaptabletools.com/docs/handbook-monitoring-data-change-history-buttons/index.md) for details of configuring the `changeHistoryButton` option
- Programmatic control (activate, suspend, read log, undo) uses [Data Change History API](https://www.adaptabletools.com/docs/technical-reference-monitoring-data-change-history/index.md)

## Making Active by Default

By default Data Change History tracking is **inactive**, and [needs to be explicitly activated](https://www.adaptabletools.com/docs/handbook-monitoring-data-change-history/index.md#setting-data-change-history-mode) in the UI.

This can be changed via the `activeByDefault` property.

### `activeByDefault`

Whether Data Change history should be Active by default

Set this property to _true_ for Data Change History tracking to be **active** by default:

```ts {3}
const adaptableOptions: AdaptableOptions = {
  dataChangeHistoryOptions: {
    activeByDefault: true,
  },
};
```

## Limiting Data Changes

Another useful property is `showDataChange`, which lets you specify which data changes appear in the monitor.

This is useful when you want to display changes only in certain columns, or user edits but not ticking data changes

### `showDataChange`

Function which specifies which Data Changes should be displayed in Data Changes Monitor

This function provides details of the Data Change and lets developers specify whether that change should be included in the Data Change screen.

The default value is `undefined` - which means that by default **all** data changes are logged

```ts
showDataChange?: (cellDataChangedInfo: CellDataChangedInfo) => boolean;
```

The function receives a [`CellDataChangedInfo`](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md) object (defined below) and returns a boolean:

| Property | Type | Description |
| --- | --- | --- |
| [changedAt](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#changedat) | `number` | Timestamp of change occurrence (in milliseconds) |
| [column](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#column) | [`AdaptableColumn`](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md)`<TData>` | Column in which cell is situated |
| [newValue](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#newvalue) | `any` | Value after the change.<br/><br/>Absent when `trigger` is `live`. |
| [oldValue](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#oldvalue) | `any` | Value before the change.<br/><br/>Absent when `trigger` is `live`. |
| [preventEdit](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#preventedit) | `boolean` | Whether the change was prevented by a validation rule |
| [primaryKeyValue](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#primarykeyvalue) | `any` | Primary Key Column&#39;s value for the row where edited cell is situated |
| [rowData](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#rowdata) | `TData` | Data in the Row |
| [rowNode](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#rownode) | `IRowNode<TData>` | AG Grid RowNode that contains the cell |
| [trigger](https://www.adaptabletools.com/docs/reference/celldatachangedinfo.md#trigger) | `'edit' \| 'tick' \| 'undo' \| 'aggChange' \| 'calculatedColumnChange' \| 'live'` | What triggered the change - user, background change, a reverted change, a<br/>derived update on a Calculated Column whose source value changed, or a<br/>live Alert rule turning true for the row (`live`: no old / new value,<br/>`column` is the rule&#39;s first Scope column when it has one). |

For instance to monitor only user edits (and not 'ticking' data changes) you can do:

```ts {3}
const adaptableOptions: AdaptableOptions = {
  dataChangeHistoryOptions: {
    showDataChange: (cellDataChangedInfo: CellDataChangedInfo) => {
      return cellDataChangedInfo.trigger == 'edit';
    },
  },
};
```

**Example: Data Change History: Limiting Changes**

Setting which edits will display in Data Change History

- `showDataChange` in `adaptableOptions.ts` excludes:
  - ticking data changes (only direct user edits are shown)
  - user edits on `updated_at` or `language`

- Click **Show** on the Data Change History toolbar to open the Data Changes Monitor
- Edit `updated_at` or `language` and note the edit does **not** appear in the log

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions, CellDataChangedInfo} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Data Change History Limiting Changes',
  dataChangeHistoryOptions: {
    activeByDefault: true,
    showDataChange: (cellDataChangeInfo: CellDataChangedInfo) => {
      if (cellDataChangeInfo.trigger !== 'edit') {
        return false;
      }
      return (
        cellDataChangeInfo.column.columnId !== 'updated_at' &&
        cellDataChangeInfo.column.columnId !== 'language'
      );
    },
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Data Change',
          Toolbars: ['DataChangeHistory'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-updated_at',
          Scope: {
            ColumnIds: ['updated_at'],
          },
          DisplayFormat: {
            Formatter: 'DateFormatter',
            Options: {
              Pattern: 'HH:mm:ss',
            },
          },
        },
      ],
    },
    FlashingCell: {
      FlashingCellDefinitions: [
        {
          Name: 'Flashing_Cell_Github',
          Scope: {
            ColumnIds: ['github_stars', 'github_watchers'],
          },
          Rule: 'ANY_CHANGE()',
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'github_watchers',
            'updated_at',
            'description',
            'created_at',
            'has_wiki',
            'pushed_at',
            'open_issues_count',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

**`src/onAdaptableReady.ts`**

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

export const onAdaptableReady = ({adaptableApi}: AdaptableReadyInfo) => {
  setInterval(() => {
    const node: any =
      adaptableApi.gridApi.getRowNodeForPrimaryKey(getRandomRowNode()); // not sure why not RowNode here?  think some mismatch...

    if (!node) {
      return;
    }
    const data: any = {...node.data};

    // Update the github_stars and github_watchers columns
    data.github_stars = data.github_stars + generateRandomInt(-3, 3);
    data.github_watchers = data.github_watchers + generateRandomInt(-2, 2);

    // Set Updated At to current date
    data.updated_at = Date.now();

    adaptableApi.gridApi.updateGridData([data]);
  }, 2000);
};

function generateRandomInt(minValue: number, maxValue: number): number {
  return Math.floor(Math.random() * (maxValue - minValue + 1) + minValue);
}

function getRandomRowNode(): number {
  const rowNodes = [
    10270250, 24195339, 11730342, 74293321, 224663696, 95797174, 76694515,
    1801829, 82095231, 130884470, 17814354, 167174,
  ];
  return rowNodes[generateRandomInt(0, rowNodes.length)];
}
```

## Show All Data Changes

By default only the **last** change for each cell is displayed in the Data Change History Monitor.

If this behaviour is not wanted, then set the `showLastDataChangeOnly` property to _false_ in order to see every change for each cell.

### `showLastDataChangeOnly`

Whether to show all changes for each cell or just the last one

This property allows you to set the Data Change History Monitor to show **all** changes to a cell, rather than just the last one (the default behaviour).

```ts {4}
// Show all changes for every Cell
const adaptableOptions: AdaptableOptions = {
  dataChangeHistoryOptions: {
    showLastDataChangeOnly: false,
  },
};
```

**Example: Data Change History: Showing all Changes**

Setting Data Change History to show all the changes made to each Cell

- `showLastDataChangeOnly: false` in `adaptableOptions.ts` keeps every change per cell in the log
- `onAdaptableReady.ts` updates `github_stars` on the first row three times; open the monitor to see three entries

- Open the Data Change History monitor after the scripted updates and confirm three changes for the same cell

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions, CellDataChangedInfo} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Data Change History Showing All Changes',
  dataChangeHistoryOptions: {
    activeByDefault: true,
    showLastDataChangeOnly: false,
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Data Change',
          Toolbars: ['DataChangeHistory'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-updated_at',
          Scope: {
            ColumnIds: ['updated_at'],
          },
          DisplayFormat: {
            Formatter: 'DateFormatter',
            Options: {
              Pattern: 'HH:mm:ss',
            },
          },
        },
      ],
    },
    FlashingCell: {
      FlashingCellDefinitions: [
        {
          Name: 'Flashing_Cell_Github',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Rule: 'ANY_CHANGE()',
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'github_watchers',
            'updated_at',
            'description',
            'created_at',
            'has_wiki',
            'pushed_at',
            'open_issues_count',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

**`src/onAdaptableReady.ts`**

```ts
import {AdaptableReadyInfo, CellUpdateRequest} from '@adaptabletools/adaptable';

export const onAdaptableReady = ({adaptableApi}: AdaptableReadyInfo) => {
  const node: any = adaptableApi.gridApi.getFirstRowNode();
  if (!node) {
    return;
  } // Update the github_stars 3 times
  var index = 0;
  const interval = setInterval(() => {
    const cellUpdateRequest: CellUpdateRequest = {
      columnId: 'github_stars',
      primaryKeyValue: adaptableApi.gridApi.getPrimaryKeyValueForRowNode(node),
      newValue: node.data.github_stars + generateRandomInt(-10, 10),
    };
    adaptableApi.gridApi.setCellValue(cellUpdateRequest);
    if (++index > 2) {
      clearInterval(interval);
      adaptableApi.dataChangeHistoryApi.openDataChangeHistorySettingsPanel();
    }
  }, 1000);
};

function generateRandomInt(minValue: number, maxValue: number): number {
  return Math.floor(Math.random() * (maxValue - minValue + 1) + minValue);
}
```

## Limiting Data Changes in Store

By default AdapTable retains **every** logged data change in State indefinitely.

This is fine if you are tracking user edits, but the store can grow unboundedly when tracking ticking data.

Use the `maxDataChangesInStore` property to cap the number of changes held in memory at any one time.

- When the cap is reached, the **oldest** change is dropped as each new change is logged
- This ensures that the store never exceeds the size you configure

### `maxDataChangesInStore`

Maximum number of Data Changes to retain in State; oldest changes are removed once the limit is reached

Set this property to cap the size of the Data Change History store.

```ts {3}
const adaptableOptions: AdaptableOptions = {
  dataChangeHistoryOptions: {
    maxDataChangesInStore: 8,
  },
};
```

When `maxDataChangesInStore` is `undefined` (the default) no cap is applied and every logged change is retained

**Example: Data Change History: Capping Store Size**

Capping the number of Data Changes retained in the store

- `maxDataChangesInStore: 8` and `showLastDataChangeOnly: false` in `adaptableOptions.ts`; ticking is driven from `onAdaptableReady.ts`
- Each tick updates a random row/column among `github_stars`, `github_watchers`, `open_issues_count`, or `updated_at`
- The monitor opens automatically; once eight entries exist, each new change drops the oldest

- Watch the Data Change History monitor as ticking updates arrive
- The list fills to eight entries and then holds steady — each new change pushes the oldest one out

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Data Change History Max Changes In Store',
  dataChangeHistoryOptions: {
    activeByDefault: true,
    maxDataChangesInStore: 8,
    showLastDataChangeOnly: false,
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Data Change',
          Toolbars: ['DataChangeHistory'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-updated_at',
          Scope: {
            ColumnIds: ['updated_at'],
          },
          DisplayFormat: {
            Formatter: 'DateFormatter',
            Options: {
              Pattern: 'HH:mm:ss',
            },
          },
        },
      ],
    },
    FlashingCell: {
      FlashingCellDefinitions: [
        {
          Name: 'Flashing_Cell_Ticking_Columns',
          Scope: {
            ColumnIds: ['github_stars', 'github_watchers', 'open_issues_count'],
          },
          Rule: 'ANY_CHANGE()',
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'github_watchers',
            'updated_at',
            'description',
            'created_at',
            'has_wiki',
            'pushed_at',
            'open_issues_count',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

**`src/onAdaptableReady.ts`**

```ts
import {AdaptableReadyInfo, CellUpdateRequest} from '@adaptabletools/adaptable';

export const onAdaptableReady = ({adaptableApi}: AdaptableReadyInfo) => {
  // Open the Data Change History Monitor so users can watch entries roll in and off
  adaptableApi.dataChangeHistoryApi.openDataChangeHistorySettingsPanel();

  const rowNodes = adaptableApi.gridApi.getAllRowNodes();
  if (!rowNodes.length) {
    return;
  }

  // Select tickable columns to update
  const tickableColumns = [
    'github_stars',
    'github_watchers',
    'open_issues_count',
    'updated_at',
  ] as const;

  setInterval(() => {
    const node: any = pickRandom(rowNodes);
    const columnId = pickRandom(tickableColumns);

    const currentValue = node.data[columnId];
    const newValue =
      columnId === 'updated_at'
        ? Date.now()
        : currentValue + generateRandomInt(-5, 5);

    const cellUpdateRequest: CellUpdateRequest = {
      columnId,
      primaryKeyValue: adaptableApi.gridApi.getPrimaryKeyValueForRowNode(node),
      newValue,
    };
    adaptableApi.gridApi.setCellValue(cellUpdateRequest);
  }, 800);
};

function pickRandom<T>(items: readonly T[]): T {
  return items[Math.floor(Math.random() * items.length)];
}

function generateRandomInt(minValue: number, maxValue: number): number {
  return Math.floor(Math.random() * (maxValue - minValue + 1) + minValue);
}
```
