Alert Definitions

An alert definition is a rule for sending a notification. It has a name, a severity, a trigger, and a list of channels. The trigger is where the work is: Trigger Type changes which fields the form shows, and each type is evaluated differently.

Before you begin

• At least one notification channel exists. Channel Configuration IDs is required and lists only saved channels. See Notification channels.
• You are signed in as an organisation member. Alert definitions are organisation-wide settings.

Open the alert definitions list

1. In the Engage sidebar, select Settings, then Alert Definitions.

The table lists every definition with Name, Trigger Type, Status, Scope, Created At, and Actions. Trigger Type can be filtered by the types in use, and Search Alert Definitions matches on name or trigger type.

Create an alert definition

1. Select Add Alert Definition. The Create Alert Definition drawer opens.
2. Complete the common fields.
3. Select a Trigger Type. The fields for that type appear below it.
4. Complete the trigger fields, then Channel Configuration IDs and Message Template.
5. Select Create.

Common fields

Field	Required	What to enter
Alert Name	Yes	A descriptive name.
Description	No	Free text.
Active	No	On by default. An inactive definition stays in the list but does not fire.
Requires Acknowledgment	No	Off by default. Marks the alert as needing manual acknowledgment.
Trigger Type	Yes	Immediate, Threshold, Schedule, or Pattern.
Severity	Yes	Low, Medium, High, Critical, or Emergency.
Cooldown Period (ms)	Yes	The minimum gap between two notifications from this definition, in milliseconds.
Channel Configuration IDs	Yes	One or more notification channels. Each option shows the channel name and its scope.
Message Template	Yes	The text of the notification.

Immediate

No further fields. The alert fires on each qualifying event, subject to the cooldown.

Threshold

Field	What to enter
Count	The number to compare against.
Operator	Greater Than, Less Than, Equal To, Greater Than or Equal, or Less Than or Equal. Defaults to greater than if left empty.
Time Window (minutes)	The window over which the count is evaluated.

Schedule

Field	What to enter
Cron Expression	A six-field cron pattern, for example 0 0 9 * * * for nine every morning.
Timezone	A timezone name such as UTC or America/New_York. Defaults to UTC if left empty.

Pattern

Field	What to enter
Consecutive Failures	How many failures in a row trigger the alert.
Same Error Code	Off by default. On, the failures must share an error code to count as a run.

Switching Trigger Type after filling a branch hides that branch's fields; only the fields of the selected type are saved.

Enable, disable, edit, or delete a definition

• Status is a switch on the row. Changing it asks Status Update Confirmation; select Enable or Disable to confirm. Engage reports Status updated successfully.
• The edit control in Actions opens the Edit Alert Definition drawer with the saved values. Select Update to save.
• The delete control in Actions asks Delete Alert Confirmation; select Delete.

How you know it worked

Engage reports Alert definition created successfully and the definition appears in the table with its Trigger Type and Status on.

When it does not work

Symptom	Cause	What to do
A message naming a field, such as Trigger type is required or Channel configuration IDs are required	A required field is empty	Complete the field named and select Create again
Channel Configuration IDs offers nothing	No notification channel has been created	Create one under Settings > Notification Channels, then reopen the drawer
Failed to create alert definition or Failed to update alert definition	Engage could not save the definition	Try again; if it persists, ask an administrator
Failed to update alert status	The status change was not saved	Refresh the list and try again

Alert definitions and fallouts

In this release, a fallout definition has no field for choosing an alert definition. The Alert Rule field is not shown in either the application or the organisation fallout form, and a fallout definition is saved with no alert attached. Alert definitions therefore run independently of fallout definitions. See Fallout definitions for what a fallout definition does control.

Application alerts

An application has a second, separate alert surface. Open the application from Applications, select the Configuration tab, then Alerts. These alerts are not alert definitions: each one is a metric query over the application's execution data with a threshold condition.

The table lists Alert Name, Channel Name, Description, and Action, with Search Alert Name above it. Select Configure Alert to open the Add Alert drawer, or Configure on a row to edit it.

The drawer has these fields:

Field	What to enter
Alert Name	Required.
Severity	Critical, Error, Warning, or Info.
Alert Description	Required.
Notification Channels	One or more of the channels from Settings > Notification Channels.

Below them, three tabs hold the query. Builder is a query builder over execution attributes with an aggregate function per query. Query With AI and Code View each show Feature In Progress and do nothing yet.

The condition reads as a sentence: send a notification when the chosen query is above, below, Equal To, or Not Equal To the threshold, At Least Once, All The Times, On Average, or in total, during the last period selected, with the threshold value and a unit of count. More options adds how often to run the alert and how many minutes of missing data should trigger a notification.

Select Save, or Update when editing. Engage reports Alert Created Successfully or Alert Updated Successfully. Deleting a row asks Delete Alert and reports Alert deleted successfully.

Next steps

If the alert should react to failed executions, continue with Managing fallouts.