Alert

The Alert Module enables the creation of powerful and flexible Alerts.

Alerts are triggered when the Rule specified in an Alert Definition is met, usually as the result of edits or 'ticking' data changes in the Grid.

note

Alert Definitions can be provided in Alert Predefined Config or created at run-time

There are many different types of Alerts that can be created (including Flashing Alerts or Validation Alerts) and a wealth of options concerning what should happen when the Alert is triggered.

Alert Trigger

The trigger (or Rule) in an Alert Definition can be one of 4 types:

important

Alerts trigger both as the result of direct user grid edits, and as data ticks in the underlying data source

Predicate

Most commonly, the Alert Definition will contain a Predicate - the same boolean function as is used as in filters - which has a type (e.g. GreaterThan) and, optionally, inputs (e.g. 100)

tip

Developers can easily provide their own Custom Predicates to create bespoke validation rules.

Boolean Query

In more advanced scenarios (e.g. if you want the Alert Definition to react not only to the data change in the cell being edited but look at other values in the row) you can, instead of a Predicate, provide a Boolean Query (i.e. one which returns true/false).

Observable Query

Alert supports Observable Queries - advanced, reative-type Queries, which are triggered as the result of changes (or lack of changes) in a particular row (or set of rows) or in the entire Grid.

For instance, you can trigger an Alert if a particular row has not changed in the last hour, or has changed 5 times in 10 minutes, or if a column / cell value is the highest that its been all day.

caution

Observable Queries require a Scope of 'Whole Row'

See the Observable Expression documentation for more information.

Aggregation Query

Alerts can also be triggered by Aggregation Queries.

These are Queries which run against aggregated data using a SUM function, e.g. fire an Alert if the Sum of 'PnL' is > 50M where Currency is Dollar.

caution

Aggregation Queries require a Scope of 'Whole Row'

See the Aggregation Expression documentation for more information.

Message Type

The MessageType of the Alert sets what type of of Message is displayed (and the colour will vary accordingly). The available values are:

  • Success - (default colour is green)

  • Info - (default colour is blue)

  • Warning - (default colour is amber)

  • Error - (default colour is red)

Alert Properties

The AlertProperties property of the AlertDefinition contains a number of properties to configure the grid's behaviour when an Alert is triggered, and is defined as follows:

PropertyDescription
DisplayNotificationDisplays a notification when Alert is triggered
HighlightCellColours updated cell using MessageType property of triggering Alert Definition
JumpToCellGrid will 'jump' to the cell which triggered the Alert
LogToConsoleLogs the Alert message to the console
PreventEditAutomatically prevent any cell edit which triggered the Alert (i.e. validation) false
ShowInDivShows Alert text in the div specificed in AlertDisplayDiv property of Alert State.

As can be seen, some of the options for displaying an Alert include:

  • Display a Notification - useful for important Alerts or where user actions are required

    tip

    The Notification can additionally include an Adaptable Form - see alert form section below - and its appearance and behaviour can be heavily customised

  • Colour the Cell where the data changed that triggered the Alert (based on the Alert's MessageType)

    note

    Unlike a Button Predefined Action, this will automatically happen as soon as the Alert is triggered.

  • Jump to Cell so that the Grid will immediately show the row which contains the cell that triggered the Alert

    note

    Unlike a Button Predefined Action, this will automatically happen as soon as the Alert is triggered.

  • Show the Alert details in a Div element (that you specify in Container Options)

    caution

    The previous way of doing this - via AlertDisplayDiv property in Alert State - is deprecated

note

All Alerts when triggered will display (and update the count) in the Alert Toolbar and Alert Tool Panel.

important

Additionally, all Alerts will fire the AlertFired event (the contents of which will be also sent to the console).

Alert Form

When the Alert is displayed in a Notification there is an option to provide an Adaptable Form inside the Alert.

tip

The Form displays in Notifications triggered by the Alert so make sure DisplayNotification is set to true in AlertProperties

There are 2 ways to provide an Alert Form

  • defining the form in full (including buttons) in Alert Options
  • providing a reduced form - with just Buttons and associated actions - in Alert Config

Full Form Definition

The best way to provide a Form to display in an Alert is to follow this 2 step process:

  1. Define the Adaptable Form in full in the alertForms section of Alert Options
  2. Reference that Form by name in the AlertForm property of the Alert Definition object in Alert Config

This allows you to provide a rich form with Adaptable Buttons that can have multiple function implementations.

Example

In the example below we have defined an Alert which will trigger if 'ItemCount' value is over 30.

This Alert displays a Notification containing a Form (entitled 'Overwrite Form') which includes:

  • a numeric field so a new 'Item Count' property
  • an overwrite button which enters the new value provided via the form (with validation)
  • an undo button which undoes the Cell Edit and reverts to the original value
const adaptableOptions: AdaptableOptions = {
alertOptions: {
alertForms: [
{
name: 'Overwrite Form',
form: {
description: 'Please enter a value < 30 or click "Undo" ',
fields: [
{
name: 'ItemCount',
label: 'Item Count',
defaultValue: '',
fieldType: 'number',
},
],
buttons: [
{
label: 'Overwrite',
disabled: (button: AdaptableButton, context: AlertButtonContext) => {
const newValue: any = context.formData?.['ItemCount'];
return (
!newValue || newValue < 0 || newValue > 30
);
},
onClick: (button: AdaptableButton, context: AlertButtonContext) => {
const columnId = context.alert.dataChangedInfo?.columnId;
const primaryKeyValue = context.alert.dataChangedInfo?.primaryKeyValue;
const newValue = context.formData?.['ItemCount'];
if (columnId && primaryKeyValue && newValue) {
adaptableApi.gridApi.setCellValue(
columnId,
newValue,
primaryKeyValue,
false
);
}
},
buttonStyle: {
tone: 'warning',
variant: 'outlined',
},
},
{
label: 'Undo',
onClick: (button: AdaptableButton, context: AlertButtonContext) => {
if (context.alert?.dataChangedInfo) {
adaptableApi.gridApi.undoCellEdit(
context.alert.dataChangedInfo
);
}
},
buttonStyle: {
tone: 'neutral',
variant: 'outlined',
},
},
],
},
},
],
},
predefinedConfig: {
Alert: {
AlertDefinitions: [
{
Scope: {
ColumnIds: ['ItemCount'],
},
MessageType: 'Warning',
Rule: {
Predicate: {
PredicateId: 'GreaterThan',
Inputs: [30],
},
},
AlertProperties: {
DisplayNotification: true,
},
AlertForm: 'Overwrite Form',
},
],
},
},
};

Form With Actions

Sometimes the full Form provided above might be overkill and you want your form just to include a few buttons with actions and no custom logic for whether they are enabled or visible.

This can be done by providing a reduced Adaptable Form in the AlertForm property of the Alert Definition object in Alert Config.

The Form will just contain buttons (which can be styled) and the onClick will wire to an Alert Action.

note

Any Alerts created at run-time by the User can only have Action Buttons

AdapTable ships with 5 Alert Actions:

  • highlight-cell
  • jump-to-cell
  • jump-to-row
  • jump-to-column
  • undo

Custom Alert Actions

Developers can easily provide additional Alert Actions at design-time.

tip

These Actions can then be referenced in Config to Alert Buttons (see below)

This is done via the actionHandlers section of Alert Options.

Each Action Handler is defined as follows:

export declare type ActionHandler = {
name: string;
handler: (button: AlertButton, context: AlertButtonContext) => void;
};

As can be seen the handler function is the same as the Alert Button onClick - taking the Button and the Alert Context and returning void.

Example

In the example below we have defined the same Alert as in the example above - which will trigger if 'ItemCount' value is over 30.

However in this example there is no form with a numeric field and an override button, but we have provided 2 buttons each linked to Actions:

  • Show Me: 2 Adaptable actions (highlight-cell, jump-to-cell) and 1 custom action (emailSupport)
  • Undo: The undo Adaptable action
const adaptableOptions: AdaptableOptions = {
alertOptions: {
// Define handlers in Alert Options
actionHandlers: [
{
name: 'emailSupport',
handler: (button: AdaptableButton, context: AlertButtonContext) => {
// provide an implementation to email Alert details
},
},
],
},
predefinedConfig: {
Alert: {
AlertDefinitions: [
{
Scope: {
ColumnIds: ['ItemCount'],
},
MessageType: 'Warning',
Rule: {
Predicate: {
PredicateId: 'GreaterThan',
Inputs: [30],
},
},
AlertProperties: {
DisplayNotification: true,
},
AlertForm: {
buttons:[
{
label: 'Show Me',
onClick: ['highlight-cell', 'jump-to-cell', 'emailSupport']
},
{
label: 'Undo',
onClick: ['undo']
}
]
}
},
],
},
},
};

Validation Alerts

Alerts can be used to prevent cell edits from happening when they break the rule set in the Alert Definition.

In this scenario AdapTable will show the Alert before the edit is committed and sent to the server.

note

This avoids the irritating round-trip scenario where an edit is made which everyone sees and then a second later the value 'jumps back' to how it was previously

To do this set the PreventEdit property in the Alert Definition to true.

important

This option was introducted in 8.2 and it replaces the now deprecated, Cell Validation Module as it provides superior functionality and options.

Overwriting Validation

Sometimes the Prevent Edit can be too strong and you might prefer to give users a 'second chance' - i.e. to provide a new value if the initial edit triggers an Alert.

This can be achieved via an Adaptable Form with 2 Buttons that reference Grid Api methods when clicked.

In the example below, we have created an Alert for when 'ItemCost' > 100 and provided a form with:

  • a single numeric input and no default value
  • a button which overwrites the proposed edited value with the one from the in put, and is disabled if the new value is not betwen 1 and 100
  • a button labeled 'undo' which when clicked overwrites the new value (with the old one)
alertOptions: {
alertForms: [
{
name: 're-price',
form: {
description: 'Please enter a value < 100 or click "Undo" ',
fields: [
{
mame: 'ItemCost',
label: 'Item Cost',
defaultValue: '',
fieldType: 'number',
},
],
buttons: [
{
label: 'Overwrite',
disabled: (button: AdaptableButton, context: AlertButtonContext) => {
const newItemCostValue: any = context.formData?.['ItemCost'];
return newItemCostValue < 0 || newItemCostValue > 100;
},
onClick: (button: AdaptableButton, context: AlertButtonContext) => {
const columnId = context.alert.dataChangedInfo?.columnId;
const primaryKeyValue = context.alert.dataChangedInfo?.primaryKeyValue;
const newValue: any = context.formData?.['ItemCost'];
if (columnId && primaryKeyValue && newValue) {
adaptableApi.gridApi.setCellValue(
columnId, newValue, primaryKeyValue, false
);
}
},
buttonStyle: {
tone: 'warning',
variant: 'outlined',
},
},
{
label: 'Undo',
onClick: (button: AdaptableButton, context: AlertButtonContext) => {
if (context.alert?.dataChangedInfo) {
adaptableApi.gridApi.undoCellEdit(
context.alert.dataChangedInfo
);
}
},
buttonStyle: {
tone: 'neutral',
variant: 'outlined',
},
},
],
},
},
],
},
PredefinedConfig:{
Alert: {
AlertDefinitions: [
{
Scope: {
ColumnIds: ['ItemCost'],
},
MessageType: 'Warning',
Rule:{
Predicate: { PredicateId: 'GreaterThan', Inputs: [100] },
}
AlertProperties: {
DisplayNotification: true,
},
AlertForm: 're-price',
},
],
},
}

Flashing Alerts

A common scenario in AdapTable is where users want a cell to flash briefly when it changes.

This is performed through Flashing Alerts - with the added advantage that it can be customised to the precise requirements of each user.

note

In versions of Adaptable prior to Version 9 there were separate Flashing Cell and Updated Row functions that provided this functionality; these have now been merged into Alerts

These can be provided at design time via the FlashingAlertDefinitions section of Alert Config or at runtime through the UI.

A Flashing Alert extends the standard Alert so it will have Scope and a Rule.

tip

This is typically set to Scope of a single column and a Predicate of 'Any Change' - but Flashing Alerts can be set up to be triggered on any kind of change

It also includes a FlashingAlertProperties object which allows you to define the Up, Down and Neutral change style, the duration and whether a single cell or whole row flashes.

Default Properties

important

Default flashing alert properties can be set in Alert Options to be used when no properties are provided.

The full object is defined as follows:

PropertyDescription
DownChangeStyleStyle for 'Down' value changes
FlashDurationDuration of Flash - can be number (in ms) or 'always'
FlashTargetShould a cell or whole row flash
NeutralChangeStyleStyle for 'Neutral' value changes
UpChangeStyleStyle for 'Up' value changes
tip

Set the duration to 'always' if the cell/row should remain coloured until it is explicitly turned off by the user

note

Doing this will replicate the behaviour of the Updated Row function that was removed in Version 9

Alert Options

The Alert Options section of Adaptable Options contains useful properties for configuring all Alert behaviour.

note

Alert Options differs governs behaviour across ALL Alerts, (e.g. where Notifications should appear).

Alert Properties, by contrast, defines how Alerts from one particular Alert Definition will behave, e.g. whether to jump to the cell)

Many of the properties set the behaviour of the Toast-style Notification that appears when Alerts are triggered.

An important property is flashingAlertDefaultProperties which allows you to specify how Flashing Cells should look by default.

tip

You can set default behaviour for Flashing Alerts in Alert Options but still override it for particular Alert Definitions in Alert Config

The full definition is as follows:

PropertyDescriptionDefault
actionHandlersonClick Handlers for Alert Buttons (defined in Alert State)
alertFormsFull definitions of Alert Forms - the names of which are provided in Alert State
cellHighlightDurationHow long (in ms) a cell will be highlighted3000
closeWhenClickedCloses Notification automatically when its clickedfalse
dataChangeDetectionPolicyWhether Alert rule should be evaluated against the rawValue or formattedValue of the changed cell data'rawValue'
durationHow long (in ms) Notifications display for3000
flashingAlertDefaultPropertiesFlashing Alert DefaultsBackColors: Green (up), Red (down), Gray (neutral), Duration: 500ms
isDraggableCan Notification be draggedfalse
maxAlertsInStoreHow many alerts held in State at any one time; when limit is breached, oldest alert will be removed20
maxNotificationsHow many Notifications can be displayed at one time3
pauseWhenHoveringPauses the Notification when mouse hovers over itfalse
positionWhere Notification will appear (if anywhere)'BottomRight'
showProgressBarShows a Progress Bar in the Notificationfalse
transitionHow Notification will appear: 'Bounce''Slide'

Notifications

As can be seen, many of the Alert Options properties relate to the appearance of the Notification that can be displayed when an Alert is triggered.

important

The Notification is only visible if the Alert Definition has DisplayNotification set to true in Alert Properties

By default the Notification will appear by sliding into the BottomRight of the screen for 3 seconds without a progress bar and cannot be dragged nor will close when it is clicked.

However all these settings are configurable in Alert Options.

caution

Unlike Alert Properties which can be set independently for each Alert Definition, Notifications are set in Alert Options and so are configured identically for every Alert which displays a notification

Events

There are 2 Adaptable Events fired by the Alert Module:

Alert Fired

The Alert Fired Event is fired every time an Alert is triggered.

It contains full details of the Alert and the associcated Alert Definition.

FlashingAlert Fired

For Flashing Alerts the Event is Flashing Alert Fired.

The EventInfo provides information about what (e.g. cell or row) was flashed, for how long, and the triggering data change.

UI Elements

Alerts includes the following UI Elements:

  • Popup - Shows a list of existing Alerts with Edit and Delete buttons. Plus an Add button to start the Alerts Wizard which facilitates the creation and editing of Alerts.

  • Toolbar - Updates when an Alert is triggered; contains an info button which when clicked gives full details of each Alert.

  • Tool Panel - Same as Toolbar above.

  • Column Menu - Add / Remove Flashing Alert (or 'Off') Menu Item in numeric columns will enable / disable Flashing Cell Module for that Column.

  • Context Menu Item - Clear Alert Menu Item clears a Cell if it has been coloured by an Alert

Entitlements

Alerts Entitlement Rules:

  • Full: Everything is available to the User

  • Hidden: Everything is hidden from the User and any Alerts supplied in Predefined Config will be ignored.

  • ReadOnly: Alerts will trigger as normal but users cannot not edit or delete them, nor create others.

Alert Predefined Config

The Alert section of AdapTable State enables Alert Definitions to be provided at design-time.

Alert Definitions

The Alert State contains a group of AlertDefinition objects - each of which defines a rule which - when met - will fire the Alert.

note

Alert Definitions can be provided at design-time (through Alert Config) or at run-time through the UI (if Entitlements allow).

Alert Definition Scope

Like many objects in AdapTable, Alert uses Scope to determine where an Alert should be applied.

The Scope can be one, some or all columns, or it can be all columns of a particular DataType (or DataTypes).

export default {
Alert: {
AlertDefinitions: [
{
Scope:
{
ColumnIds: ['InvoicedCost'],
}
MessageType: 'Warning',
Rule:{
Predicate:
{
PredicateId: 'GreaterThan',
Inputs: [2000],
},
},
AlertProperties: {
DisplayNotification: true,
},
},
{
Scope:
{
ColumnIds: ['ItemCount'],
}
MessageType: 'Info',
Rule:{
Predicate:
{
PredicateId: 'PercentChange',
Inputs: [100],
},
},
AlertProperties: {
DisplayNotification: false,
},
},
],
},
} as PredefinedConfig;

Alert API

The Alert Api contains a number of useful function for creating Alerts and managing the Alert section of AdapTable State.

FAQ

Can we show Alerts in the System Tray?

Not directly as its not something AdapTable can easily access. But we do publish the Alert Fired Event which allows you to show the Alert in multiple places.

I don't want my Alerts to pop-up. Can I prevent that?

Yes, when you create an Alert Definition you can stipulate, among other things, whether the Alert will display a Notification. See Alert Predefined Config for the full Alert Definition.

What is the difference between the Alert and the Reminder functions?

Reminders are, indeed, similar to Alerts but there are 2 key differences:

  1. the message is hard-coded rather than dynamically derived from the nature of the data change
  2. reminders are triggered, not when something changes in the Grid, but according to a Schedule set by the User when creating the Reminder.

Why add Prevent Edit Alerts which perform validation on the client - surely it should take place on the server?

You are right, validation should ideally take place on the server and hopefully it does for our users.

And AdapTable offers Server Validation for this reason.

Instead prevent edit Alerts validation specifically deals with 3 common use cases:

  1. add an extra level of validation so that you can prevent edits which are usually permitted, but which in particular scenarios or use cases should be avoided

  2. avoid unnecessary round trips to the server, particularly if this has other knock-on consequences or effect other users that might see their screen flash first with the new value and then again with the old value

  3. as a temporary measure before Server Validation has been added; like all AdapTable objects, Alert Definitions will come into effect immediately after that they are created in the UI - there is no down-time needed, nor any custom development required, and no systems need to be restarted

Flashing Alert FAQ

Can we change the colours for a Flashing Cell column?

Yes you can choose any colours you want for both the up and down change.

Can we change the default colours?

Not at runtime - default colours can only be set at design tine in Alert Options

Can we change the colour based on the row (e.g. depending on other values in the row, the flash will be different colours or duration)?

Yes, simply create a new Flashing Alert Definition for that particular rule

Can we turn on flashing for columns which don't contain numbers?

Yes, Flashing Alert Definitions can be provided for any column or combination of columns

Can we add set the flash to remain in place until I see it?

Yes, set the FlashDuration to always and it will remain coloured until explicitly cleared by the user

What is the difference between Alert Properties and Alert Options?

Alert Properties will define how Alerts trigged by one particular Alert Definition will behave. So you can set up different properties (e.g whether to show a notification or jump to the cell) based on the Alert Definition.

Alert Options governs behaviour across ALL Alerts (e.g. where Notifications should appear).

More Information