Module 09: Alerts & Notifications

In the previous modules you configured delivery timing for the TRAINING.MYGASHUB.SETTLEMENTS dataset and attached quality and critical checks to it. In this module you will see how the platform raises alerts when that dataset is late, missing or fails its checks, and how to be notified about them.

Alerts and Alert Records​

The platform separates the definition of an alert from the alerts that are actually raised:

There are four alert types:

This module concentrates on DatasetAlert, because it covers the two cases we care about: delivery failures and quality check violations.

Step 1: Understand When Dataset Alerts Are Raised​

When a dataset is late, missing, or fails a quality check, the platform raises a DatasetAlert for it. For the settlements dataset this is driven by the configuration you created in the Dataset Monitoring and Quality Checks modules:

Each alert record carries the ondate it is about, an issue describing the problem, a message, an impact of critical, high, medium (the default) or low, and a status of open or closed.

Step 2: Find the Alerts Raised for Your Dataset​

//#region
use training

// All open dataset alerts for the settlements dataset
openAlerts = find ${alertrecord} where type = "DatasetAlert" and name = "TRAINING.MYGASHUB.SETTLEMENTS" and status = "open"

for rec in openAlerts
    print rec.ondate + " " + rec.issue + " (" + rec.impact + "): " + rec.message
next
//#endregion

If nothing is returned, your dataset has no open alerts. Step 4 shows how to raise one yourself so you have something to work with.

Step 3: Define a Dataset Alert​

An alert definition lets you describe the alert and set its default impact. A DatasetAlert needs a name and the dsid of the dataset.

//#region
use training

a = Alert("TRAINING.MYGASHUB.SETTLEMENTS")
a.type = "DatasetAlert"
a.dsid = "TRAINING.MYGASHUB.SETTLEMENTS"
a.description = "Settlement prices for the training gas hub are late, missing or failed checks"
a.impact = "high"

save ${alert:a}
print "Dataset alert saved"
//#endregion

Step 4: Raise an Alert Record from a Script​

As well as the alerts the platform raises, you can raise your own, for example when an analyst spots a problem that no check covers.

//#region
use training

rec = AlertRecord("TRAINING.MYGASHUB.SETTLEMENTS", "DatasetAlert")
rec.ondate = "2025-03-03"
rec.issue = "price-review"
rec.message = "Settlement price for 2025-03-03 is under review with the counterparty"
rec.impact = "medium"

save ${alertrecord:rec}
print "Alert record raised"
//#endregion

Run the script a second time with a different message. Because the type, name, ondate and issue match the open record, the platform adds the new message to the timeline of the same record instead of creating a duplicate.

Step 5: Get Notified About Delivery Failures​

To be told when something goes wrong, add an automation on the event that raises the alert. A dataset alert is raised when a dataset is late or missing, so an automation on the late and missing actions of the dataset service notifies you at the same time.

//#region
use training

a = AutomationBuilder("dataset", "private", "TRAINING.MYGASHUB.SETTLEMENTS").build()
conds = []
actions = ["late", "missing"]
for act in actions
    c = SimpleObject()
    c.service = "dataset"
    c.source = "private"
    c.id = "TRAINING.MYGASHUB.SETTLEMENTS"
    c.action = act
    conds.add(c)
next
a.conditions = conds
a.target = "odsl.email"
a.template = "When 'TRAINING.MYGASHUB.SETTLEMENTS' is late, send an email to [to] with subject [subject]"
a.icon = "envelope-at text-outlook"
a.properties.to = "your.name@example.com"
a.properties.subject = "Settlements late or missing: TRAINING.MYGASHUB.SETTLEMENTS"
a.properties.attachment = false
save ${automation:a}
print "Delivery failure automation saved"
//#endregion

Replace the to address with your own. An automation fires when any of its conditions match, so this single automation covers both cases.

Step 6: Get Notified When an Alert Is Raised​

When a dataset is late or missing, or fails its checks, the platform raises an alert about it. To be notified whenever an alert about the settlements dataset is raised or reopened, watch the alert service with the dataset id.

//#region
use training

a = AutomationBuilder("alert", "private", "TRAINING.MYGASHUB.SETTLEMENTS").build()
conds = []
actions = ["raised", "reopened"]
for act in actions
    c = SimpleObject()
    c.service = "alert"
    c.source = "private"
    c.id = "TRAINING.MYGASHUB.SETTLEMENTS"
    c.action = act
    conds.add(c)
next
a.conditions = conds
a.target = "odsl.email"
a.template = "When an alert is raised for 'TRAINING.MYGASHUB.SETTLEMENTS', send an email to [to] with subject [subject]"
a.icon = "envelope-at text-outlook"
a.properties.to = "your.name@example.com"
a.properties.subject = "ALERT: TRAINING.MYGASHUB.SETTLEMENTS"
a.properties.attachment = false
save ${automation:a}
print "Alert automation saved"
//#endregion

See Alert notifications and automations for the other alert actions.

Step 7: Close an Alert​

When the issue has been resolved, close the record by setting its status to closed and saving it.

//#region
use training

openAlerts = find ${alertrecord} where type = "DatasetAlert" and name = "TRAINING.MYGASHUB.SETTLEMENTS" and issue = "price-review" and status = "open"

for rec in openAlerts
    rec.status = "closed"
    rec.message = "Price confirmed with the counterparty"
    save ${alertrecord:rec}
    print "Closed alert for " + rec.ondate
next
//#endregion

Metric Alerts (optional)​

A MetricAlert checks a platform metric on a schedule and raises an alert when it crosses a threshold. It needs a metric, how the metric is observed over the lookback (for example summed), an operator (gt, gte, lt or lte), a checkFrequency such as 15m, and either an absoluteThreshold or a dynamic threshold. See the Alerts topic for the full property list.

Summary​

Exercise​

1. Create a delivery failure automation for TRAINING.MYGASHUB.NOMINATIONS
2. Raise an alert record for TRAINING.MYGASHUB.NOMINATIONS with an impact of low, then run the script again with a new message and confirm only one open record exists
3. Close the record and confirm it no longer appears in the open alerts query

For more detail, see Alerts, the Alert and AlertRecord variable reference and the Alert service.