Create Alerts in Dashboards
In dashboards, you can set up alerts to monitor key metrics and receive notifications when specific conditions are met. Alerts are triggered by changes in metric values, allowing you to stay informed about important updates without the need for constant monitoring.
Admin Setup Required
Before you can create alerts, your administrator must configure one or more destinations and ensure you have the necessary workspace permissions, as described in Automation in Dashboards.
SDK and Embedding
Alerts work with SDK version 10.12.0 or newer. If you use these features with SDK version older than 10.12.0, it might cause problems with embedding.
Delivery Methods
When an alert is triggered, the notification will be delivered based on the selected destination.
If an email destination is chosen, you’ll receive a structured email notification, and the format will vary based on the alert type.
If you create an alert for a visualization that only uses a metric, the email will appear as shown in this example:
If the visualization includes attributes to slice the metric and you select a specific attribute value to monitor, the email will follow this format:
Alternatively, if you choose to monitor all attribute values, the email will look like this:
Custom Email Appearance
Your organization’s white-labeling and customization settings may alter the appearance of the email, as defined by your administrator. For more information, see Customize Emails.
Alternatively, if a webhook destination is selected, a JSON payload will be sent to the webhook for further processing in external systems, managed by the administrator.
Create Alert
Note that some visualizations include attributes, while others do not. For widgets without attributes, you create a condition based solely on a specific metric value. For widgets that include attributes, you have two alert options:
- All attribute values: This triggers an alert whenever the metric, sliced by any attribute value, meets the condition.
- Specific attribute value: This triggers an alert only when the condition is met for the metric sliced by a chosen attribute value.
Follow the steps below to set up a new alert for a dashboard widget.
Steps:
Open a dashboard.
Hover over a widget, click the … button and select Alerts.
The alert creation dialog opens.
Configure the alert’s condition, metric, an attribute value (optional) and destination.
You can click the cogwheel button to configure the Trigger setting: The trigger can be set to send the alert every time alerts are evaluated, assuming the conditions are met, or trigger just once, after which the alert becomes paused.
Once configured, click Create.
Optionally you can then edit, pause, or unpause the alert from the widget:
or the dashboard-wide alert list:
To create and manage alerts via the API, you can call the API endpoint /api/v1/entities/workspaces/<workspaceId>/automations using POST, GET, PATCH, DELETE, and PUT methods.
To create a new alert make the following API call:
curl $HOST_URL/api/v1/entities/workspaces/<workspace_id>/automations \
-H "Content-Type: application/vnd.gooddata.api+json" \
-H "Accept: application/vnd.gooddata.api+json" \
-H "Authorization: Bearer $API_TOKEN" \
-X POST \
-d '{
"data": {
"type": "automation",
"id": "<alert_id>",
"attributes": {
"title": "<alert_display_name>",
"details": {
"widgetName": "<widget_display_name>"
},
"state": "ACTIVE",
"metadata": {
"widget": "<widget_id>"
},
"alert": {
"condition": {
"comparison": {
"operator": "<comparison_operator>",
"left": {
"localIdentifier": "<metric_id>",
"title": "<metric_display_name>",
"format": "<metric_format>"
},
"right": {
"value": <value_to_compare_to>
}
}
},
"execution": {
"filters": [
{
"relativeDateFilter": {
"dataset": {
"identifier": {
"id": "<date_dataset_id>",
"type": "dataset"
}
},
"granularity": "<granularity>",
"from": <relative_date_from>,
"to": <relative_date_to>
}
},
{
"positiveAttributeFilter": {
"label": {
"localIdentifier": "<attribute_id>"
},
"in": {
"values": [
"<attribute_value>"
]
}
}
}
],
"measures": [
{
"localIdentifier": "<metric_id>",
"definition": {
"measure": {
"item": {
"identifier": {
"id": "<metric_id>",
"type": "fact"
}
},
"aggregation": "<aggregation_type>"
}
}
}
],
"auxMeasures": [],
"attributes": [
{
"label": {
"identifier": {
"id": "<attribute_id>",
"type": "label"
}
},
"localIdentifier": "<attribute_id>"
}
]
}
}
},
"relationships": {
"recipients": {
"data": [
{
"type": "user",
"id": "<user_id>"
}
]
},
"notificationChannel": {
"data": {
"type": "notificationChannel",
"id": "<destination_id>"
}
},
"analyticalDashboard": {
"data": {
"type": "analyticalDashboard",
"id": "<dashboard_id>"
}
}
}
}
}'
a real-life example might look like this:
curl https://frosty-cat.trial.cloud.gooddata.com/api/v1/entities/workspaces/e45864d8057f40a09957ba1bdd3b5139/automations \
-H "Content-Type: application/vnd.gooddata.api+json" \
-H "Accept: application/vnd.gooddata.api+json" \
-H "Authorization: Bearer ZWRtaG46Ym9vdHN1cmFwOkdkG05hczUaKm==" \
-X POST \
-d '{
"data": {
"type": "automation",
"id": "f7d38bc0-dce7-4a97-9121-f41e09d49824",
"attributes": {
"title": "Sum of Price",
"details": {
"widgetName": "L1"
},
"state": "ACTIVE",
"metadata": {
"widget": "71b8d924-2d3c-4ba0-ba94-cdc01b8d93a5"
},
"alert": {
"condition": {
"comparison": {
"operator": "GREATER_THAN",
"left": {
"localIdentifier": "9e734dc8f3b94e43a917e141e1d4a77d",
"title": "Sum of Price",
"format": "#,##0.00"
},
"right": {
"value": 50000
}
}
},
"execution": {
"filters": [
{
"relativeDateFilter": {
"dataset": {
"identifier": {
"id": "date",
"type": "dataset"
}
},
"granularity": "MONTH",
"from": -12,
"to": -12
}
},
{
"positiveAttributeFilter": {
"label": {
"localIdentifier": "476dded1390e4a70b8a68cca12752d03"
},
"in": {
"values": [
"Northeast"
]
}
}
}
],
"measures": [
{
"localIdentifier": "9e734dc8f3b94e43a917e141e1d4a77d",
"definition": {
"measure": {
"item": {
"identifier": {
"id": "price",
"type": "fact"
}
},
"aggregation": "SUM"
}
}
}
],
"auxMeasures": [],
"attributes": [
{
"label": {
"identifier": {
"id": "region",
"type": "label"
}
},
"localIdentifier": "476dded1390e4a70b8a68cca12752d03"
}
]
}
}
},
"relationships": {
"recipients": {
"data": [
{
"type": "user",
"id": "alex.doe"
}
]
},
"notificationChannel": {
"data": {
"type": "notificationChannel",
"id": "92684672-0efc-4845-aaa4-f7eaaac2682f"
}
},
"analyticalDashboard": {
"data": {
"type": "analyticalDashboard",
"id": "53258179-00e1-46d5-a6a5-347e91309624"
}
}
}
}
}'
Period Comparison
You can create alerts that monitor changes in a metric’s value by comparing it to a previous period. For instance, if you have a line chart sliced by a date attribute, grouped into a specific time period, such as a Quarter:
When setting up an alert for a dashboard widget based on this visualization, additional comparison options will be available:
You can select either a relative (percentage) or an absolute (numeric) comparison of the metric’s value in the current period against the previous one. There’s also an option to compare the current period against the same period in the previous year, which is useful for observing seasonal trends:
The following types of visualizations support period comparison alerts:
- Line chart
- Column chart
- Bar chart
- Repeater
- Combo chart
- Bullet chart
- Bubble chart
- Pie chart
- Donut chart
- Waterfall chart
- Pyramid chart
- Funnel chart
- Pivot table
- Stacked area chart
Visualization Configuration Requirement
When creating or editing visualizations in Analytical Designer, ensure any date filters do not exclude the current period. If the current period is filtered out, a comparison alert cannot be created for the visualization.
Filters
When creating an alert, the active dashboard filters are saved as part of the alert, and the alert will be displayed and triggered based on those filters.
Disabling
You can disable the ability to create new alerts for a specific visualization by editing it in the Analytical Designer. To do this, go to the Interactions tab while editing the visualization:
