Alerts

You can set up an alert to trigger on a variety of conditions that you specify.

Create an alert

Follow these steps to create an alert.

If you click the New alert icon from the data cube view, some of the alert's configurable fields are pre-filled based on values in the data cube from which you created the new alert. You can modify all fields before creating the alert.

Click the New alert icon:

• The New alert icon is on the Data cube view:
• The New alert icon is also on the Alerts view:

Complete the following fields on the Create new alert page:

Alert name

The alert's name or title that appears in emails, webhook notifications, and in the alerts view.

Severity

The severity can be any of the following: success, info, error, or warning. The severity you select affects the alert's color and icon in the UI.

Data cube

The data cube that has the data for this alert to evaluate. If you create an alert from the data cube view, this field populates automatically. Otherwise, this field defaults to the first data cube listed in the drop-down.

Check every

Controls how often the conditions of the alert are evaluated. Setting this field to one hour, for instance, checks the alert's conditions against the alert's data cube every hour.

Time frame

The temporal window against which the alert's conditions are evaluated. Setting this field to one day, for instance, results in data for the last day (defined from the moment the alert is evaluated) being checked against the alert's conditions. A best practice is to make Time frame equal to or greater than Check every. By default, Time frame and Check every are equal.

Filters

You can define one or more filters to delimit the alert data gathered during alert evaluation. You cannot define a static time filter because an alert is always evaluated on a dynamic time frame.

Look at

Depending on the alert's type, Look at lets you define conditions for your alert either in terms of measures over the entire data cube or in terms of individual values for a dimension in the data cube's Show bar. When selecting dimension values for this field, you must specify both the dimension you want to evaluate and its sorting criteria.

Comparison

You can either set an alert to trigger based on an absolute condition (when a certain measure reaches a certain value, for example) or based on a relative condition (when a measure grows by more than a certain delta, for example). You must first specify a comparison period.

Conditions

When the data in your data cube is evaluated and the conditions you specify here are true, your alert is triggered. You can specify one or more conditions. If you specify more than one, you can select whether all conditions must be true to trigger the alert or whether at least one condition must be true to trigger the alert (Any condition).

Measure

You must specify the measure to which your Conditions apply.

Condition body

The condition body contains an operator (> or <), a value, and possibly another field, based on whether the comparison field is populated or not.

Edit an alert

You can edit an Alert configuration by clicking on the ellipsis button for an alert in the alerts listing view:

Alternatively, you can edit an alert by clicking the alert's name. Then, click Edit alert.

Receive an alert

Only users — not roles — can receive alert emails. Additionally, depending on your Pivot configuration, the Delivery options view might not be available. If you are running Pivot in default-user mode, and you don't support either email or webhooks, this view is hidden.

To specify the method by which to send your alert and also who should receive it, first click Delivery options on the Create new alert page.

The Create a new report page appears with the following fields:

Recipients

Choose a list of users or roles you want to have read access to this alert. Read access enables you to see an alert, and possibly receive emails about the alert (if your email is specified in the Email field). Read access doesn't let you modify the alert.

Admins

Choose a list of users or roles you want to have write access to this alert. Write access enables you to see an alert and its feed, and possibly receive emails about the alert (if your email is specified in the Email field). Write access also lets you edit the alert.

Email

Users with a check in the checkbox next to their email address receive an email every time the alert is triggered.

Webhooks

Webhooks let you get notified about triggered alerts by a third-party service. Pivot alerts have built-in support for both Slack and custom webhooks. For Slack webhooks, the payload is predefined. You only need a webhook URL (see Create a Slack webhook URL). For custom webhooks, you can customize what is sent and how it is sent to the service you want to connect with your alert configuration.

Configure an alert email

You can send an email to an alert's chosen recipients when an alert is triggered. To send an email, you must first configure Pivot to send emails.

You can send both default and custom alert emails.

The default template for an alert email is in the Pivot configuration file:

 name: 'alert'
    templateLanguage: 'mustache'
    subject: '{{{title}}} has triggered'
    html:
      ...
            {{#link}}
            <p>
              <a href="{{link}}">Learn more</a>
            </p>
            {{/link}}
          </body>
        </html>

The following interpolation properties are available for use in both the email's subject and body:

Property	Description
title	The alert's title
link	A link to a Pivot data cube view for the report instance. This requires the linkHostName config setting to be configured

To specify a custom alert email template, provide an entry in the emailTemplates block with the name alert in the Pivot configuration file:

emailTemplates:
  - name: 'alert'
    subject: '${title} has triggered'
    html: |
      <h2>Oh my look, an alert: ${title}</h2>
      <p>
        ${summary}
      </p>
      <p>
        Learn more: http://localhost:9095${link}
      </p>

In this template, the following interpolation properties are available for use in both the email's subject and body:

Property	Description
title	The Alert name you specified when creating or editing the alert
Summary	A brief summary of what triggered the alert
Link	A relative link to the event that triggered the alert, relative to the installation. In the example above, the link is localhost

Configure a Slack webhook URL

A user needs the ManageAlertsWebhooks permission to modify an alert's webhooks.

Alerts support sending info to a Slack webhook. You can generate a webhook URL by following steps 1 to 3 of this tutorial, and then pasting the URL into a new webhook as shown below:

You can also define a webhook as custom and customize its payload, meaning what is sent to the service targeted by the URL. This payload contains a variety of keys that are interpolated as follows:

Title

The Alert name you specified when creating or editing the alert

Summary

A brief summary of what triggered the alert

Link

A relative link to the event that triggered the alert, relative to the installation. In the example above, the link is localhost

TriggerDate

The timestamp for when the trigger fired, in seconds

Color

The color related to the alert's type -- blue for info, green for success, red for error, and yellow for warning

Severity

The alert's type, as defined in its configuration

Footer

The alert's sender, which is either Imply or the user who sent the notification

For reference, here is Slack's default payload:

{
  "attachments": [
    {
      "fallback": "<title>",
      "color": "<color>",
      "title": "<title>",
      "title_link": "<link>",
      "text": "<summary>",
      "ts": <triggerDate>
    }
  ]
}