Using the Alerts feature on the Enterprise Data Platform, you can set custom alerts on datasets that can be triggered when certain conditions are met, based on the contents of the dataset. Alerts can help answer questions like “tell me when this dataset has not been updated for more than a week,” “tell me when the number of violent crimes in district 4 this month exceeds 20,” and “let me know whenever there is a crime near my child’s school.”
The following article will describe how you can create and manage alerts on your site.
Viewing and Managing Alerts
Alerts and their settings can all be accessed through the notification bell located in the internal navigation bar.
The bell will look as it has previously, but on click will open an in-product notifications curtain. This section will have three tabs: Alerts, Notifications, and Product Updates. User alerts will appear in the Alerts tab.
By Selecting Settings, users can view and manage all of their active alerts. On the Notifications & Alerts tab, you can choose if you would like to receive notifications through the platform or email when an alert is triggered. You can view, edit, pause or delete your alerts by selecting My Alerts.
Creating a Dataset Alert
The first step in creating an alert on a dataset is to navigate to the Primer page of the dataset. From there you will see a Create Alert button. Pressing this button will upon up a new pop-up where you can create your new alert.
Threshold, Incident and Time-Based Alerts
There are three types of custom alerts, Threshold Alerts, Incident Alerts, and Time-Based Alerts.
A threshold alert is against a query spanning the ENTIRE dataset regardless of the time it was entered into the dataset. Threshold alerts evaluate every time the underlying dataset is updated.
An incident alert is against a query with a new row or newly updated row since the point in time you created the query. Incident alerts evaluate every time the underlying dataset is updated.
A time-based alert checks a condition in the dataset on a predetermined schedule, instead of when the dataset is updated.
For example, let's say you are looking at a dataset of Chicago Crimes and are interested in being alerted when there is a homicide.
In this example:
- A Threshold alert for a homicide against Chicago Crimes would immediately alert next time the dataset is updated even if there were no new homicides.
- An Incident Alert for a homicide against Chicago Crimes would only alert the next time a new row has been added or an existing row has been updated to show a homicide. If the data update contains multiple rows for homicide only one alert will occur.
- A Time-Based alert would check to see if a condition has met within the dataset at a particular point in time, for example on a Monday morning before an executive review meeting.
Snoozing Threshold Alerts
Threshold alerts are most frequently used to allow executives and strategic leaders in government to be notified when there is an important change or when a key SLA or threshold has been breached in a program. Often, the changes required to address that issue take time to implement and take effect.
After selecting the Threshold Alert option, users can set an "auto-snooze" period associated with that alert that will pause the alert after it fires for a defined period of time. For example, if a threshold in the data is breached, a user may want to add a week-long auto-snooze period, which would cause the alert to evaluate again the following week after giving some time for changes in approach to be reflected in the data.
Create a Custom Alert
The first option in creating a custom alert is to choose the Alert Type. As mentioned above, you can choose from three different alert types: Threshold, Incident, and Time-based.
The next step will be to set the parameters of your alert.
In the example below, I am setting an alert on a Chicago based crimes dataset to look for a homicide in a general area. To do so simply choose your column from the drop-down, and operator and then a value.
Once you have added all your fields you will need to click Validate, if your alert looks good, you can click next to proceed. You will also need to set the Alert Name in this section before proceeding to the next step.
You will now select how you want to be alerted, of which there are two options.
Rolling: Rolling queries will execute every time the dataset updates and the alert condition is met.
Single: Single alerts will be sent immediately once the alert is triggered and the alert will then pause itself.
Create an Advanced Alert
An advanced alert takes a custom SoQL statement. An alert will be sent when the dataset is updated and the SoQL statement returns one or more rows. The developer site has additional documentation on SoQL Functions and SoQL Queries.
The following will show an example of how to construct a SoQl statement to create an alert. Follow the same instructions as above to open the Alert editor, this time select the Advanced Alert tab.
1.) First, we want to select all rows that will satisfy a condition, start by entering the text in italics below:
select * where
2.) Next let's look for a specific type of crime, assaults. To do so we will add:
primary_type = "Assault"
Our full query will now read
select * where primary_type = "Assault"
3.) Now let's look for only assaults that involve a handgun, in this case, we will look at a description field for any descriptions that include handguns.
description like "handgun"
We will add this parameter to our query using "and"
select * where primary_type = "Assault" and description like "handgun"
4.) Finally, let's add one more condition to only be alerted when there was an arrest as well.
select * where primary_type = "Assault" and description like "handgun" and arrest = "true"
Now that we have created the SoQL statement, name your alert and select Validate!
If your validation does not work, there are a couple common issues to check.
- The syntax contains spelling or character errors
- There are missing quotation marks around your value
- You are not using the API field names for the columns in the dataset.
After configuring an alert, users have the option of adding a message or description to that alert to add context for the users that receive it. That description will both appear in the email and in-product notification that users receive.
Alert descriptions can include HTML tags, including adding in images or embedded content via iFrames. For security and compliance reasons, embedded Data & Insights visualizations do not appear in emails but do appear in in-product notifications.
Sharing Alert Subscriptions
After creating an alert, users have the option to share a copy of their alert subscription with other users. This allows multiple users to receive the same notification at the same time and help coordinate between groups of stakeholders.