Observable Alerts

View as Markdown

Summary

  • Observable Alerts fire when a live Observable Expression Rule becomes true
  • They are ideal for Alerts that are based on history or time conditions
  • Examples include change counts, highs and lows, silence, grid-wide activity, and row-event counts
  • The Rule is a boolean Expression built from Observable Functions (that use curly braces)

Observable Alerts watch how data has changed (or, indeed not changed) in AG Grid over time.

They leverage AdapTable's recorded cell / row history.

Typical use cases for Observable Alerts include:

  • a cell has changed 3 times in the last 2 minutes
  • a value is at its highest in the last hour
  • there have been no ticks for 5 seconds
  • a column changed grid-wide N times within a window
  • at least N rows were added or removed in a timeframe

Find Out More

See Observable Expressions for full details of the many observable-related functions available

Observable Functions

There are many Observable Functions available.

The ones which are most commonly used in Alerts are:

FunctionExample Alert Rule
CHANGE_COUNTCHANGE_COUNT{[price], WITHIN(5m)} >= 3 — choppy
NO_CHANGESNO_CHANGES{[price], WITHIN(20s)} — this row has gone quiet
NET_CHANGENET_CHANGE{[price], WITHIN(1h)} > 10 — large absolute move
PERCENT_CHANGEPERCENT_CHANGE{[price], WITHIN(1h)} > 5 — up more than 5% in the hour
HIGHEST / LOWEST[price] = HIGHEST{[price], WITHIN(1d)} — at the daily high
PREVIOUS[price] > PREVIOUS{[price]} — higher than the last tick
ROW_AGEROW_AGE{} < 30s — row added in the last 30 seconds
ROWS_ADDED / ROWS_REMOVEDROWS_ADDED{WITHIN(1m)} >= 3 — burst of adds in a minute

Find Out More

See Observable Expressions for the full catalogue and timeframes (e.g. WITHIN, LAST_N, ALL_ROWS())

Creating Alert Expressions

Observable Functions always return a value.

Note

The return value can be of any kind, though it is most commonly a number

However Alert Expressions need to return a boolean - so they trigger if they evaluate as true.

Accordingly, in order to create an Alert Rule, you need 2 steps:

  1. create a normal Observable Expression:
CHANGE_COUNT{[price], WITHIN(5m)}
  1. Wrap that Observable Expression inside a comparison operation:
CHANGE_COUNT{[price], WITHIN(5m)} >
Developer Guide

Providing Observable Alerts in Initial State

const initialState: InitialState = {
  Alert: {
    AlertDefinitions: [
      {
        Name: 'alert-stars-choppy',
        Type: 'Observable',
        MessageType: 'Info',
        MessageHeader: 'Choppy stars',
        Scope: {All: true},
        Rule: 'CHANGE_COUNT{[github_stars], WITHIN(2m)} >= 3',
        AlertProperties: {
          DisplayNotification: true,
        },
      },
      {
        Name: 'alert-issues-at-high',
        Type: 'Observable',
        MessageType: 'Success',
        Scope: {All: true},
        Rule: "[open_issues_count] = HIGHEST{[open_issues_count], WITHIN(1h)} AND [language] = 'JavaScript'",
        AlertProperties: {
          DisplayNotification: true,
          HighlightCell: true,
        },
      },
    ],
  },
};
1
Set Type to Observable (recommended)

Set Type: 'Observable' for live rules. Use Scope: { All: true } unless the rule is grid-level only.

2
Boolean Rule with Observable Functions

Wrap observable functions (curly braces) in a comparison so the rule evaluates to true / false.

3
TriggerPolicy (optional)

Observable alerts default to firing when the rule becomes true (TriggerPolicy.FireOn: 'BecomeTrue'). See Alerts Technical Reference.

Per Row Changes

The most common Observable Alert use case is watching each row's own change history.

Alerts: Observing Row Changes
Fork
  • This demo showcases 2 Observable Alerts which focus on per-row changes:
    • Tell me if Github Stars has changed 3 times in this row within 2 minutes: CHANGE_COUNT{[github_stars], WITHIN(2m)} >= 3
    • Tell me if Open Issues is at its 1-hour high on JavaScript rows: [open_issues_count] = HIGHEST{[open_issues_count], WITHIN(1h)} AND [language] = 'JavaScript'
Try It Out
  • Click the Add Star Action Column button next to Github Stars; once it is clicked 3 times in a row, the Info Alert will be triggered
  • Click the Open an Issue button next to Open Issues on a JavaScript row to push it to a new high
Loading demo…

Grid-wide Changes

Observable Alerts can also fire based on activitiy across the whole Grid.

This is by done by using the ALL_ROWS() keyword.

Hint

This is useful when you care about overall activity rather than a single row

Alerts: Observing Grid Changes
Fork
  • This example contains 2 Observable Alerts which operate over the whole Grid:
    • Tell me if Language changed 3 times anywhere in the Grid within 5 minutes - CHANGE_COUNT{[language], WITHIN(5m), ALL_ROWS()} >= 3
    • Tell me if Github Stars changed twice within a minute, counting only MIT License rows - CHANGE_COUNT{[github_stars] WHERE [license] = 'MIT License', WITHIN(1m), ALL_ROWS()} >= 2
Loading demo…

No Changes

Observable Alerts are also ideal for detecting silence — when expected ticks stop.

Note

  • This is particularly useful if you have ticking data or you expect some changes at some point
  • NO_CHANGES is the Function for this: it returns a boolean, so it can be the Alert Rule on its own

No Changes Per Row

Watch one column on each row:

// Fires per row when that row's price has been quiet for 20 seconds
NO_CHANGES{[price], WITHIN(20s)}

Or watch every column on the row with ANY_COL():

NO_CHANGES{ANY_COL(), WITHIN(20s)}

No Changes Per Grid

Add ALL_ROWS() for one shared reading across the whole Grid.

// Fires once when no row has changed price in 5 seconds
NO_CHANGES{[price], WITHIN(5s), ALL_ROWS()}

Hint

  • ANY_COL() with ALL_ROWS() is the usual “feed stalled” pattern — silence anywhere, on any column
  • DisplaySystemStatusMessage on the Alert writes the same message into the System Status bar
NO_CHANGES{ANY_COL(), WITHIN(10s), ALL_ROWS()}
Alerts: Observing No Changes
Fork
  • A live price feed updates Last several times a second, and the Column flashes on each tick
  • The Alert Rule is NO_CHANGES{ANY_COL(), WITHIN(2s), ALL_ROWS(), TRIGGER('tick')}
  • DisplaySystemStatusMessage is on, so when the Rule fires the System Status bar shows an Error
Try It Out
  • Watch prices tick and flash
  • Click Simulate system down in 10 secs — ticking continues
  • After 10 seconds the feed stops; 2 seconds of silence later the Error System Status appears
  • Click Resume Feed to restore the ticks
Loading demo…

Row Change Counts

AdapTable provides a Row Change Alert which is a specialist Alert Type.

This common use case occurs when Rows are added or removed from the Grid.

However it is possible to extend these with fully-powered Observable Expressions — e.g. alert only when a specific number of rows have been added within a timeframe:

 // Tell me if more than 10 rows were added in the last minute
 ROWS_ADDED{WITHIN(1m)} > 10
Alerts: Row Add Burst
Fork
  • Alert Type is Observable (not Row Change)
  • Rule: ROWS_ADDED{WITHIN(30s)} >= 3 — fires when at least 3 rows are added within 30 seconds
  • Unlike a Row Change Alert, this does not fire on every single add — only when the count in the window crosses the threshold
Try It Out
  • Click the Add Row Dashboard button three times (within 30 seconds) and note the Warning Alert
Loading demo…

Suspending Observable Alerts

When an Observable Alert is suspended, the subscription is removed.

It will then be re-created when unsuspended.

Caution

  • This means that any changes in the data during the Alert's suspension are not observed
  • The count / watch starts again from scratch (rather than continues) when the Alert is unsuspended