Alerts Module

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.

warning

Alerts only work when using the ClientSideRowModel - see Server Functionality Guide for more details

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 Expression

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 Expression (i.e. one which returns true/false).

Observable Expression

The Alert Module fully supports Observable Expressions.

These are advanced, reactive-type Expressions, which are triggered by AdaptableRX in response to changes (or lack of changes) in a particular row (or set of rows) or in the entire Grid.

For instance, an Alert can fire 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 Expressions require a Scope of 'Whole Row'

Aggregation Expression

The Alert Module also supports Aggregation Expressions.

These, too are reactive-type Expressions which are triggered by AdaptableRX.

Aggregation Expressions run against aggregated data using a SUM function; for instance e.g. an Alert will fire if the Sum of 'PnL' is > 50M where Currency is Dollar.

caution

Aggregation Expressions require a Scope of 'Whole Row'

Message Type

The MessageType property of the Alert sets what type of of Message is displayed.

It is of type AdaptableMessageType which has 4 available values.

AdapTable associates each value with a corresponding CSS Variable to set the colour of the message and Alert:

TypeCSS VariableDefault Colour
Info--ab-color-infoBlue
Success--ab-color-successGreen
Warning--ab-color-warnOrange
Error--ab-color-errorRed
tip

The colour returned by any of these variables can be set when creating a Custom Theme

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

    important

    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

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 Notification 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 = {
notificationsOptions: {
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<AlertButtonContext>,
context: AlertButtonContext) => {
const newValue: any = context.formData?.['ItemCount'];
return (
!newValue || newValue < 0 || newValue > 30
);
},
onClick: (button: AdaptableButton<AlertButtonContext>,
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<AlertButtonContext>,
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 the form just to include a few buttons with actions and no custom logic for whether they are enabled or visible.

This can be achieved by providing a reduced Adaptable Form - via 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 contain Action Buttons

AdapTable ships with 6 Alert Actions:

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

The 'suspend' Action essentially sets the IsSuspended property in the Alert Definition to true

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 and jump-to-cell
  • Undo: The undo Adaptable action
note

Because this is Predefined Config Buttons, Label, ButtonStyle and Tooltip are all in PascalCase (as per the AdapTable convention)

const demoConfig: PredefinedConfig = {
Alert: {
AlertDefinitions: [
{
Scope: {
ColumnIds: ['ItemCount'],
},
MessageType: 'Warning',
Rule: {
Predicate: {
PredicateId: 'GreaterThan',
Inputs: [30],
},
},
AlertProperties: {
DisplayNotification: true,
},
AlertForm: {
Buttons:[
{
Label: 'Show Me',
Action: ['highlight-cell', 'jump-to-cell']
ButtonStyle: {
tone: 'accent',
},
Tooltip: 'Show Cell',
},
{
Label: 'Undo',
Action: ['undo']
}
]
}
},
],
},
},
} as PredefinedConfig;

Custom Alert Actions

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

important

These Actions can then be referenced in Predefined Config and wired up to Alert Buttons (see below)

This is done via the actionHandlers section of Notification 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

This example is the same as above but we have added a custom action - emailSupport - for which we provide the Action Handler:

const adaptableOptions: AdaptableOptions = {
notificationsOptions: {
// Define handlers in Alert Options
actionHandlers: [
{
name: 'emailSupport',
handler: (button: AdaptableButton<AlertButtonContext>,
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',
Action: ['highlight-cell', 'emailSupport']
},
]
}
},
],
},
},
};

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)
notificationsOptions: {
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<AlertButtonContext>,
context: AlertButtonContext) => {
const newItemCostValue: any = context.formData?.['ItemCost'];
return newItemCostValue < 0 || newItemCostValue > 100;
},
onClick: (button: AdaptableButton<AlertButtonContext>,
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<AlertButtonContext>,
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.

Suspending Alerts

Like all objects that derive from SuspendableObject, Alerts have an IsSuspended property which disable activity without requiring a full delete and re-creation.

When an Alert is suspended it is fully canceled: no Alert Messages will be fired, no toast notifications will display and nothing will show in the Alert Toolbar and Tool Panel.

If it is a Reactive Alert, then the subscription is removed when the Alert is suspended and will be re-created when un-suspended.

caution

This means that any changes in the data during the Alert's suspension are not observed and the count / watch starts again from scratch when the Alert is unuspended

tip

To keep the Alerts running but reduce notifications, either set DisplayNotification to false in Alert Properties or change the default notification behaviour in Notification Options

Notifications Options

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

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

note

Notifications Options governs behaviour across anywhere Notifications will appear (including, but not limited to, Alerts).

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

important

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

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

UI Entitlements

UI Entitlements behaviour is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is that Alerts will trigger as normal but users cannot create, edit, delete or suspend Alert Definitions; Alerts may be still cleared however.

Alert Predefined Config

The Predefined Configuration for the Alert Module

Alert Config primarily contains 2 collections of 'Definitions':

PropertyDescriptionDefault
AlertDefinitionsAlert Definitions - will trigger Alerts when rule is metnull
FlashingAlertDefinitionsFlashing Alert Definitions - will colour cells/rows when rule is metnull

Alert Definition

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).

The Alert Definition object is as follows:

PropertyDescription
AlertFormForm to display in Alert with buttons and inputs
AlertPropertiesSeries of properties which set what happens when Alert is triggered
MessageTextAlert Message - can be string or function; if not provided AdapTable creates dynamically using Rule & Scope
MessageTypeType of Alert: 'Info', 'Success', 'Warning', 'Error'; influences Alert colour, icon and logging

Base Alert Definition

The BaseAlertDefinition is defined as follows:

PropertyDescription
RuleWhen Alert should be triggered
ScopeWhere Alert can be triggered: one, some or all columns or DataTypes
note

Either Predicate or Query should be set in order to trigger the Alert when the rule is met

Alert Predicate

For most use cases the Predicate should be used which is defined as follows:

PropertyDescription
InputsOptional inputs - needed to evaluate some Predicates (e.g. 'GreaterThan')
PredicateIdId of Predicate (e.g. 'Equals', 'GreaterThan')

Alert Query

However in more advanced cases, a Query should be used.

Alert Config Example

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;

In this example we have created 2 Alert Definitions:

  • On InvoicedCost column which will warn (and show a popup) when the value is > 2000

  • On ItemCount column which will show info alert (but not show a popup) if the new value is more than double (i.e. has percent change > 100).


Flashing Alert Definition

The Flashing Alert Definition is used to define Flashing Alerts.

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

MethodDescription
addAlertDefinition(alertDefinition)Adds new Alert Definition
addFlashingAlertDefinition(flashingAlertDefinition)Adds a Flashing Alert Definition to State
addFlashingAlertDefinitions(flashingAlertDefinitions)Adds provided Flashing Alert Definitions
displayAlert(alertToShow)Displays (fully formed) inputted Alert to the User
displayMessageAlertPopup(alertToDisplay)Displays given Alert as a Popup
editAlertDefinition(alertDefinition)Edits Alert in State with given one
editFlashingAlertDefinition(flashingAlertDefinition)Edits Flashing Alert in State with given one
editFlashingAlertDefinitions(flashingAlertDefinitions)Edits provided Flashing Alert Definitions
executeAlertAction(actionName, details)Runs after an Alert Action is invoked
executeAlertButton(button, context)Runs after a button in an Alert Form is clicked
getActiveNonReactiveAlertDefinitions()Retrieves all active (non-suspended) Alert Definitions in Alert State which are NOT Reactive (BooleanQuery)
getActiveNonReactiveFlashingAlertDefinitions()Retrieves all active (non-suspended) Alert Definitions in Alert State which are NOT Reactive (BooleanQuery)
getActiveReactiveAlertDefinitions()Retrieves all active (non-suspended) Alert Definitions in Alert State which are reactive (ObservableQuery & AggregationQuery)
getActiveReactiveFlashingAlertDefinitions()Retrieves all active (non-suspended) Flashing Alert Definitions in Alert State which are reactive (ObservableQuery & AggregationQuery)
getAdaptableFormByName(name)Retrieeves the Adaptable Form with the given name
getAlertDefinitionById(id)Retrieves alert definition by id
getAlertDefinitions()Retrieves all Alert Definitions in Alert State
getAlertDefinitionsWithAllowEdit()Retrieves all Alert Definitions which allow a Cell Edit
getAlertDefinitionsWithPreventEdit()Retrieves all Alert Definitions which prevent a Cell Edit
getAlertDescription(alertDefinition, dataChangedInfo)Returns a description of an Alert Definition
getAlertPredicateDefs()Retrieves all Predicate Defs with Module Scope of Alert
getAlertPredicateDefsForScope(scope)Retrieves all Predicate Defs that match given Scope
getAlertRuleDescription(alertDefinition)Returns a description of an Alert Definition's Rule
getAlertState()Retrieves Alert section from Adaptable State
getFlashingAlertDefinitionById(id)Retrieves Flashing Alert Definition By Id
getFlashingAlertDefinitions()Retrieves all Flashing Alert Definitions in Alert State
getFlashingAlertFlashTarget(flashingAlertDefinition)Returns where a Flashing Alert Definition will flash a single cell or a whole row
getNonReactiveAlertDefinitions()Retrieves all Alert Definitions in Alert State which are NOT Reactive (BooleanQuery)
getNonReactiveFlashingAlertDefinitions()Retrieves all Alert Definitions in Alert State which are NOT Reactive (BooleanQuery)
getReactiveAlertDefinitions()Retrieves all Alert Definitions in Alert State which are reactive (ObservableQuery & AggregationQuery)
getReactiveFlashingAlertDefinitions()Retrieves all Flashing Alert Definitions in Alert State which are reactive (ObservableQuery & AggregationQuery)
publishAlertFiredEvent(alertToFire)Publishes an event when an Alert is triggered
showAlert(alertHeader, alertMessage, alertDefinition, dataChangedInfo)Creates Alert formed from inputted values and displays it.
showAlertError(alertHeader, alertMessage)Creates Alert formed from inputted values and displays it as Error Alert.
showAlertInfo(alertHeader, alertMessage)Creates Alert formed from inputted values and displays it as Info Alert.
showAlertPopup()Opens the Alert popup screen
showAlertSuccess(alertHeader, alertMessage)Creates Alert formed from inputted values and displays it as Succcess Alert.
showAlertWarning(alertHeader, alertMessage)Creates Alert formed from inputted values and displays it as Warning Alert.
showFlashingAlert(flashingAlertToShow)Displays a Flashing Alert
suspendAlertDefinition(alertDefinition)Suspends Alert Definition
suspendFlashingAlertDefinition(flashingAlertDefinition)Suspends a Flashing Alert Definition
unSuspendAlertDefinition(alertDefinition)Activates a suspended Alert Definition
unSuspendFlashingAlertDefinition(flashingAlertDefinition)Activates a suspended Flashing Alert Definition

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 Notification 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