# Configuring Alerts

Canonical page: https://www.adaptabletools.com/docs/handbook-alerting-configuring

- Alerts can be provided at design-time through Alert Initial State
- The Alert Options section of Adaptable Options contains many properties for configuring Alert behaviour

Developers are able to provide Alert Definitions and configure Alerts behaviour at design-time.

## Alert Definitions

Alert Definitions can be provided in [Alert Initial State](https://www.adaptabletools.com/docs/technical-reference-alerting/index.md) or created at run-time

This will ensure that the Alerts will fire as necessary each time the Application loads, and that any changes will be stored with Adaptable State.

## Alert Options

There are many options in [Alert Options](https://www.adaptabletools.com/docs/technical-reference-alerting/index.md) that can be set to manage the behaviour of Alerts.

### Highlight Duration

Developers can set the highlight durations for Rows, Cells and the Alert Status Bar Panel.

### `cellHighlightDuration`

How long (in ms) a Cell will be highlighted when an Alert fires

One of the [Alert Behaviours](https://www.adaptabletools.com/docs/handbook-alerting-behaviours/index.md) that can be provided for an Alert is to highlight the Cell which caused the Alert to fire.

This is set in milliseconds and defaults to 2000 (i.e. 2 seconds) but can be changed in this property.

```ts {4}
// Set Cells to be Highlighted for 4 seconds when an Alert is fired with behaviour of 'Highlight Cell'
const adaptableOptions: AdaptableOptions = {
  alertOptions: {
    cellHighlightDuration: 4000,
  },
};
```

### `rowHighlightDuration`

How long (in ms) a Row will be highlighted when an Alert fires

One of the [Alert Behaviours](https://www.adaptabletools.com/docs/handbook-alerting-behaviours/index.md) that can be provided for an Alert is to highlight the Row which contains the Cell that caused the Alert to fire.

This is set in milliseconds and defaults to 4000 (i.e. 4 seconds) but can be changed in this property.

```ts {4}
// Set Rows to be Highlighted for 5 seconds when an Alert is fired with behaviour of 'Highlight Row'
const adaptableOptions: AdaptableOptions = {
  alertOptions: {
    rowHighlightDuration: 5000,
  },
};
```

### `statusbarHighlightDuration`

How long (in ms) Alert panel in Status Bar is highlighted when an Alert Fires

If the Alert Status Panel has been supplied to the [AdapTable Status Bar](https://www.adaptabletools.com/docs/ui-status-bar/index.md) it will be highlighted when an Alert fires.

The Highlight colour will be in accordance with the Message Type of the Alert

The duration of the Highlight defaults to 2000 milliseconds (i.e. 2 seconds) but this can be changed in this property.

```ts {4}
// Set Alert Status Panel in Status Bar to be Highlighted for 5 seconds when an Alert is fired
const adaptableOptions: AdaptableOptions = {
  alertOptions: {
    statusbarHighlightDuration: 5000,
  },
};
```

### Highlight Style

This defaults to the Alert's `MessageType` colour but you can provide an [Adaptable Style](https://www.adaptabletools.com/docs/ui-tutorial-providing-adaptable-style/index.md) instead

### Cell Change Behaviour

Developers can configure the cell change behaviour for triggering Alerts

### `dataChangeDetectionPolicy`

Whether an Alert rule is evaluated against the rawValue or formattedValue of the changed cell data

By default AdapTable will trigger an Alert if the change in a cell's raw value triggers the Rule provided in the Alert Definition.

This can sometimes cause excessive Alerts e.g. if the 5th decimal place in cell value changes for a currency amount which essentially stays the same.

In this case, set this property to `formattedValue` and the Alert will only trigger if the value displayed in the Cell changes.

```ts {4}
// Set Alerts to trigger only when the Cell's Display (and not underlying) value changes
const adaptableOptions: AdaptableOptions = {
  alertOptions: {
    dataChangeDetectionPolicy: 'formattedValue',
  },
};
```

### Number of Alerts Saved

### `maxAlertsInStore`

How many triggered Alerts are held in State at any one time

AdapTable caches Alerts when they are fired in the Grid (as the result of an Alert Definition being triggered).

It will store up to 20 Alerts - so when the limit is breached, the oldest Alert will be removed.

This property can be used to configure for a different number of Alerts to be stored.

```ts {4}
// Cache 50 Alerts (instead of default of 20)
const adaptableOptions: AdaptableOptions = {
  alertOptions: {
    maxAlertsInStore: 50,
  },
};
```

### Consolidating Batch Alerts

Sometimes a single action (e.g. [Bulk Update](https://www.adaptabletools.com/docs/handbook-editing-bulk-update/index.md), [Smart Edit](https://www.adaptabletools.com/docs/handbook-editing-smart-edit/index.md), or `gridApi.setCellValues`), can updates several cells simultaneously.

By default each cell update will raise a separate Alert.

AdapTable provides an option to consolidate Alerts from the same Definition into **one** Alert notification — with a count of how many cells triggered it.

### `consolidateBatchAlerts`

Consolidate Alerts from the same Definition when a batch action updates multiple cells

Per-cell effects still run for every change (cell / row highlighting, console logging and the `AlertFired` event). Only the stored Alert, the toast notification and any jump-to-cell / jump-to-row are consolidated.

Alerts that use a bespoke [Alert Form](https://www.adaptabletools.com/docs/handbook-alerting-notifications/index.md#alert-forms) are never consolidated.

```ts {3}
const adaptableOptions: AdaptableOptions = {
  alertOptions: {
    consolidateBatchAlerts: true,
  },
};
```

**Example: Alerts: Consolidating Batch Updates**

One Alert when five cells update in a single batch

- `consolidateBatchAlerts` is _true_ (the default)
- An Alert fires on any change to `Github Stars` and displays a Notification
- The **Update 5 Cells** button changes the first 5 `Github Stars` values in one batch

- Click **Update 5 Cells** - Five cells highlight, but the Alert Toolbar / toast shows a single Alert ("5 cells triggered this Alert")

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  [template]
  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 {
  AdaptableButton,
  AdaptableOptions,
  CellUpdateRequest,
  CustomToolbarButtonContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Consolidate Batch Alerts',
  alertOptions: {
    consolidateBatchAlerts: true,
  },
  dashboardOptions: {
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarButtons: [
          {
            label: 'Update 5 Cells',
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const rowNodes = context.adaptableApi.gridApi.getVisibleRowNodes().slice(0, 5);
              const cellUpdateRequests: CellUpdateRequest[] = rowNodes.map((rowNode) => ({
                columnId: 'github_stars',
                newValue: (rowNode.data?.github_stars ?? 0) + 1,
                primaryKeyValue: rowNode.data?.id,
                rowNode,
              }));
              context.adaptableApi.gridApi.setCellValues(cellUpdateRequests);
            },
            buttonStyle: {
              tone: 'accent',
              variant: 'raised',
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['Alert'],
      Tabs: [
        {
          Name: 'Toolbars',
          Toolbars: ['Alert', 'ButtonToolbar'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Alert'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-github-stars-change',
          MessageType: 'Warning',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Rule: 'ANY_CHANGE()',
          AlertProperties: {
            HighlightCell: true,
            DisplayNotification: true,
          },
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'github_watchers',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```
