Alerts · 2021.09

Use alerts to track events in your data. An alert monitors for when one or more measures matches configurable conditions. You can choose how you want to be notified when an alert gets triggered.

Create a new alert

You cannot currently trigger an alert when no new data has been ingested. You also cannot trigger an alert when the conditions you specify do not match any rows in your data.

Follow these steps to create a new alert:

Click the New alert icon on the Data cube page:
The Create new alert page appears. If you click the New alert icon from the data cube view, some of the alert's configurable fields are pre-populated with values from the data cube. You can modify all fields before saving the alert:

Field	Description
Alert name	Enter a name for your new alert. This name is also the alert's title in the alerts view. The name also appears in emails or webhook notifications.
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	Specify the data cube that has the data you want the alert to monitor.
Check every	This controls how often you want the alert to run.
Time frame	The time frame controls how much data the alert can monitor every time it runs. Setting this field to one day, for instance, results in the alert querying data for the previous day (defined from the moment the alert is evaluated). 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.
Look at	Select "Overall values" if you want to evaluate against a measure, and "Dimension values" to evaluate against a dimension.
Comparison	Select "None" if you want the alert to trigger based on an absolute condition, such as when a certain measure is greater than a certain value. For a relative condition, such as when a measure changes by a certain value, You must first specify a comparison period.
Conditions	When 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.
Measure	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 you select a time period in the comparison field 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:

Click Delivery options on the Create new alert page.

new alert delivery setup

On the new page that appears, complete the following fields:

Field	Description
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 Configure 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.

Here is the default subject line: subject: '[{{{severity}}}] {{{title}}} was triggered on {{{triggerDate}}}

Here is the default markup:

<!doctype html>
  <html>
    <head>
      <meta name="viewport" content="width=device-width">
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <title>{{title}}</title>
      <style>
        html {
          font-family: sans-serif;
        }

        h2 {
          font-weight: initial;
          color: #1c1c1c;
        }

        dt {
          float: left;
          clear: left;
          width: 100px;
          color: #969696;
        }

        dd {
          margin: 0 0 0 100px;
          padding: 0 0 0.5em 0;
          height: 18px;
        }

        a {
          text-decoration: none;
          color: white;
          background-color: #258bdd;
          padding: 11px 16px 9px 16px;
          font-size: 13px;
        }

        table {
          border-collapse: collapse;
          font-size: 0.8rem;
        }

        td, th {
          border-bottom: 1px solid rgb(232, 232, 232);
          padding: 10px 20px;
        }

        th {
          color: #969696
        }

        td {
          text-align: left;
        }

        tr:nth-child(even) td {
          background-color: rgb(250,250,250);
        }

        tr:nth-child(odd) td {
          background-color: rgb(245,245,245);
        }

      </style>
    </head>
    <body>
      <dl>
        <dt>Data cube</dt>
        <dd>{{dataCubeTitle}}</dd>

        <dt>Time frame</dt>
        <dd>{{timeFrame}}</dd>

        <dt>Filter</dt>
        <dd>{{filter}}</dd>

        <dt>Condition</dt>
        <dd>{{condition}}</dd>
        {{^summaries.1}}
          <dt>Event</dt>
          <dd>{{summaries.0.event}}</dd>
        {{/summaries.1}}
      </dl>

      {{#summaries.1}}
        <table>
          <thead>
            <td scope="col">{{splitTitle}}</td>
            <td scope="col">Event</td>
          </thead>
          <tbody>
            {{#summaries}}
            <tr>
              <td>{{value}}</td>
              <td>{{event}}</td>
            </tr>
            {{/summaries}}
          </tbody>
        </table>
      {{/summaries.1}}


      {{#link}}
      <p>
        <a href="{{link}}">View</a>
      </p>
      {{/link}}
    </body>
  </html>

You can use the following interpolation properties 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.

Configure a Slack webhook URL

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

You can send info to a Slack webhook:

Generate a webhook URL by following steps 1 to 3 of this tutorial.
Then, paste the URL into a new webhook as shown below:

alert new webhook

You can also define a webhook as custom and customize its payload. This payload contains a variety of keys that are interpolated as follows:

Field	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
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

Here is Slack's default payload:

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