Alerts & Reports

👤 This documentation is intended for Primary Contributors and Workspace Admins. Check with your Team Admin for additional access.

Overview

The Alerts & Reports feature in Preset enables users to easily create event-triggered notifications (i.e., alerts) or scheduled notifications (i.e., reports).

Reports provide a snapshot of a dashboard or chart along with a link that enables recipients to browse directly to Preset further explore the visualization or dashboard. Alerts provide a custom link that facilitates viewing and further exploration.

This topic explores this functionality. First, though, let's discuss the definition of an alert and report in Preset.

What is an Alert?

An alert provides a custom link to a chart or an entire dashboard and is triggered when an event occurs. An event is a logical condition in your data, such as when a failed logon attempt occurs. Alerts are delivered via a notification channel; currently, options include e-mail and Slack.

What is a Report?

A report provides a snapshot of a chart or an entire dashboard as well as a link for further slicing & dicing of the query. A report, however, runs on a defined schedule (e.g., at 4pm every day, every week, etc.). Reports are delivered via a notification channel; currently, options include e-mail and Slack.

Navigating to Alerts & Reports

In the Toolbar, hover your cursor over Settings and then, in the drop-down menu, select Alerts & Reports.

Interface

Alerts Screen

 Reports Screen

Alerts and Reports Tab

When you browse to the Alerts & Reports screen, the Alerts interface appears by default. You can easily control what content you'd like to view by selecting the Alerts or Reports tab at the top of the screen.

Last Updated

Below the Alerts and Reports tabs is Last Updated information — this simply conveys when the screen was last updated with data. You can force refresh the page by selecting the circular Refresh icon.

Filters and Search

The filters and search features enable you to quickly find the alert or report that you're looking for, which is inavaluable when there are many entries.
Available filters include the following:

• Created By: Select a user to display alerts or reports created by that person.
• Status: Select an option to display alerts or reports that match the selected status. Available status options include:
  • Any (default): Displays all entries regardless of status.
  • Success: Displays entries that ran successfully.
  • Working: Displays entries that are currently being processed.
  • Error: Displays entries that did not successfully run.
  • Not Triggered: Displays entries with a trigger that has not yet been activated.
  • On Grace: Displays entries that are currently in a defined grace period.

To use the Search feature, simply enter a term in the text-entry field and hit  or select the magnifying glass icon. A list of entries that include your search criteria will appear in the table.

Table Column Headers

The Alerts and Reports tables include the following column headers:

• Last Run: The date, time, and UTC hour difference when the entry last ran.
• Name: The name of the alert or report, as defined when adding or editing the entry.
• Schedule: The defined schedule of the alert or report (e.g., every hour, every minute, etc.).
• Notification Method: One or more icons that indicate whether notifications will be sent by e-mail and/or via Slack.
• Owners: Icons that indicate the owner(s) of the alert or report.
• Active: Toggle switch that indicates whether the alert or report is currently enabled or not.
• Actions (visible on cursor hover): Icons that enable you to access the execution log, edit the entry, or delete the entry (please see descriptions of each below).

How to Create an Alert

After navigating to the Alerts & Reports screen, you'll be taken to the Alerts interface by default. To create a new alert, select + Alert.

The Add Alert window appears.

Define Basic Alert Details

To start, we need to define some basic details for your new alert. In this walkthrough tutorial, we will create an alert that is triggered when there is a failed user logon attempt within the last 24 hours.

Let's start with the horizontal panel across the top of the Add Alert window.

In the Alert Name field (required), enter a name for your new alert. In this use case, we'll call it Failed logon attempts.

Next, in the Owners field (required), select one or more owners for the alert. An owner has the ability to edit an alert.

Lastly, in the Description field, enter a short but meaningful description of the alert. We called ours Failed logon attempt checked daily.

The Active toggle switch is automatically enabled. Our alert's Basic Information looks as follows:

Define the Alert Condition

Next, we will move to the Alert Condition panel. This area is used to define the event that triggers the activation and notification of the alert.

In the Source field (required), select the dataset that the alert will analyze.

In the SQL Query field (required), enter a SQL statement that defines the nature of the alert. In the graphic below, the SQL statement instructs Preset to count the number of failed logon attempts in the selected datasource.

In the Trigger Alert If... field (required), define the condition and, in the Value field (required), enter the associated value of the condition. In the example shown, the alert is triggered when there is a value that is greater than 0 (i.e., a failed logon attempt was discovered).

Define the Alert Condition Schedule

This panel is used to define the frequency at which the data is checked to see if the defined condition has been met.

Define the Alert Condition Schedule

Specify Time
The first schedule option enables you to specify a highly granular schedule based on your specific requirements. Data can be checked every minute, hour, day, week, month, or year, The day, week, month, and year options all allow you to define a schedule down to the hour & minute granularity.

Check or Enter CRON
After setting a schedule, the subsequent CRON field will automatically populate with an equivalent CRON expression that represents your defined schedule.

Alternatively, you can also directly enter a CRON expression by selecting the secondary radio button and entering the expression in the CRON Schedule field.

Select Timezone
In the Timezone field, select the drop-down menu and choose your timezone.

Define Schedule Settings

In the Log Retention field (required), enter the number of days that the alert will be stored in the execution log (please see How to Use the Execution Log below for more information). By default, this is set to 90 days.

In the Working Timeout field (required), enter the number of seconds that the alert job is allowed to run before it results in an automatic timeout. By default, this is set to 3600 seconds.

In the Grace Period field, enter the number of seconds that should pass before the alert can trigger relative to when a previous alert was triggered. If an alert triggers within this period, its status will be On Grace and the alert's evaluation will commence when this period concludes. By default, this is set to 14400 seconds.

Define Message Content

In the Message Content section, select either the Dashboard or Chart radio button. Then, in the drop-down field, select the relevant dashboard or chart — a custom link will be prepared and sent based on the defined notification method (below).

Select the Ignore cache when generating screenshot checkbox to produce real-time non-cached data.

Define Notification Method

In the Notification Method section, select Add notification method. The Select delivery method drop-down field appears.

Select this field and then select either Email or Slack, as needed. On selection, you will be prompted to enter an e-mail address.

Good job, your alert is ready to go! To finalize your alert, select Add.

After your alert has been created, it will appear in the Alerts table:

How to Create a Report

After navigating to the Alerts & Reports screen, you'll be taken to the Alerts interface by default. To navigate to the Reports screen, select the Reports tab and, to create a new report, select + Report.

The Add Report panel appears.

Define Basic Report Details

To start, we need to define some basic details for your new report. In this walkthrough tutorial, we will create a report of a sales dashboard that is sent via e-mail every Monday at 9:00am.

Let's start with the horizontal panel across the top of the Add Report panel.

In the Report Name field (required), enter a name for your new report. In this use case, we'll call it Weekly Sales Dashboard Report.

Next, in the Owners field (required), select one or more owners for the report. An owner has the ability to edit a report.

Lastly, in the Description field, enter a short but meaningful description of the report. We called ours Weekly sales report.

The Active toggle switch is automatically enabled. Our report's Basic Information looks as follows:

Define the Report Schedule

This panel is used to define how frequently the report will be sent to a defined notification channel(s).

Specify Time
The first schedule option enables you to specify a highly granular schedule based on your specific requirements. Data can be checked every minute, hour, day, week, month, or year, The day, week, month, and year options all allow you to define a schedule down to the hour & minute granularity.

Check or Enter CRON
After setting a schedule, the subsequent CRON field will automatically populate with an equivalent CRON expression that represents your defined schedule.

Alternatively, you can also directly enter a CRON expression by selecting the secondary radio button and entering the expression in the CRON Schedule field.

Select Timezone
In the Timezone field, select the drop-down menu and choose your timezone.

Define Schedule Settings

In the Log Retention field (required), enter the number of days that the report will be stored in the execution log (please see How to Use the Execution Log below for more information). By default, this is set to 90 days.

In the Working Timeout field (required), enter the number of seconds that the report job is allowed to run before it results in an automatic timeout. By default, this is set to 3600 seconds.

Define Message Content

In the Message Content section, select either the Dashboard or Chart radio button. Then, in the drop-down field, select the relevant dashboard or chart — a screenshot of the dashboard or chart will be sent along with a link.

When sending a chart, be sure indicate whether a screenshot will be sent (in PNG format) or as a CSV file.

Select the Ignore cache when generating screenshot checkbox to produce real-time non-cached data.

Define Notification Method

In the Notification Method section, select Add notification method. The Select delivery method drop-down field appears.

Select this field and then select either Email or Slack, as needed. On selection, you will be prompted to enter an e-mail address. In this example, we will send the dashboard to an e-mail address.

Good job, your report is ready to go! To finalize your report, select Add.

After your report has been created, it will appear in the Reports table.

How to Schedule from the Dashboard or Chart Interface

A report can be scheduled via a dashboard or via a chart.

Via a Dashboard

View a dashboard and, in the top right corner, select the ellipsis icon and then Set up an email report.

Via a Chart

View a chart and, in the top right corner, select the ellipsis icon and then Set up an email report.

Configure the Scheduled Report

In the Report Name field (required), enter a memorable name for the new report and, in the Description field, enter a brief description of the report.

Here's an example:

Scheduling a New Report

After the word Every, select the frequency of the report.

Options include:

• Year
• Month
• Week
• Day
• Hour
• Minute

After you select one of the above, the scheduler will present options that are relevant to your choice.

Here are some examples:

Daily Report

Every day at 2pm

Every day at 6am and 2pm

Weekly Report

Every Tuesday and Thursday at 10:30am

Every Friday at 4pm and 4:30pm

Monthly Report

Every month on the 11th at 11am

Every month on the 11th and 22nd, and also on Fridays, at 4:30pm

The Timezone field defaults to your current location — use the drop-down menu to change this value, if needed.

Define Message Content

There are two ways to deliver your chart: as an image file or as a CSV file.

Select the Image (PNG) embedded in email field to receive the chart as an image that is directly embedded within the e-mail's message body.

Select the Formatted CSV attached in email field to receive the chart's raw data as a comma-separated value file that is attached to the e-mail.

In either case, you will be provided with a link to view the chart/dashboard within Preset.

Finalize the Scheduled Report

When done, select Save.

Great work! Your schedule has now been created.

To verify, select Settings → Alerts & Reports → Reports tab.

How to Use the Execution Log to View Errors

The Execution Log is a listing of all individual executions of an alert or report.

You can navigate to an execution log by selecting the Alerts or Reports tab and then hovering your cursor over an alert or report row.

Under the Actions header, select Execution Log.

The execution log for the selected alert or report will appear.

Column headers on this table include:

• State: The state of the operation as indicated by an icon (e.g., Report sending, Report sent).
• Scheduled at: The date & time when the alert or report was scheduled to run (report) or check for a trigger condition (alert).
• Start at: The date & time when the alert or report executed.
• Duration: The length of the execution.
• Value: The value returned from the defined condition (alert).
• Error Message: Any error messages generated from the execution.

Log Message Definitions

• Report Schedule is still working, refusing to re-compute: An alert/report started it's evaluation but it's last state is "Working" so it refuses to continue. Prevents concurrent alerts and reports if a previous alert query takes more time to complete then the actual cron cycle, queries can start to build up.
• Report Schedule reached a working timeout: An alert/report started its evaluation but its last state is "Working", but it's working for more time then the working timeout value. The current state of the alert is changed to "Nothing triggered" to release the working state.
• Alert fired during grace period: An alert evaluation started but its last state was "Alert Triggered", if this state happened within the grace period. Then it will not continue and log this message.
• Alert query returned more than one row: The alert SQL query must only return 1 row.
• Alert query returned more then one column: The alert SQL query must only return 1 column.
• Alert query returned a non-number value: The alert config validates with numerical comparison but the SQL returned a non numerical value (a string for example).

All the other messages should be errors from invalid SQL queries.

Getting Notified of Alert or Report Errors

If an alert or report fails to be executed, the owner of the alert or report will receive a notification via email (regardless of the original notification method) on the error. Recipients of the alerts or reports will not be notified of any errors during execution. Owners can then use the logs to check the error message for resolution.

How to Edit an Alert or Report

You can edit an alert or report by selecting the Alerts or Reports tab and then hovering your cursor over an alert or report row.

Under the Actions header, select the pencil Edit icon.

Modify any fields as needed. When done, select Save.

How to Delete an Alert or Report

You can delete an alert or report by selecting the Alerts or Reports tab and then hovering your cursor over an alert or report row.

Under the Actions header, select the trash bin Delete icon.

The Delete alert? or Delete report? window appears — type "DELETE" and then select Delete to confirm the deletion.

How to Bulk Delete Alerts or Reports

You can delete multiple alerts or reports easily by using the Bulk Select feature. To do this, navigate to the appropriate screen by selecting the Alerts or Reports tab and then select Bulk Select.

Each alert or report entry will now have a checkbox on the far left of the table. You can select multiple checkboxes to indicate entries for deletion.

Alternatively, if you wish to delete all entries, you can select the top checkbox on the header row (as displayed in the graphic below).

To delete selected entries, select Delete.

The Please confirm window appears — type "DELETE" and then select Delete to confirm the deletion.