Alerts and Scheduled Exports in Dashboards

This experimental feature allows users to enhance their dashboard experience by setting up automated alerts and scheduled exports. Alerts can notify users when specific conditions are met, such as reaching certain metric thresholds, while scheduled exports enable users to receive regular snapshots of dashboard data. These features are particularly useful for keeping track of key performance indicators without constantly monitoring dashboards in real-time.

Both alerts and exports can be sent via email or as a JSON payload to a webhook, providing seamless integration with external systems such as workflow automation tools or notification platforms. For example, alerts can be used to trigger actions in a third-party system when thresholds are met, and exports can automate the distribution of dashboard insights to team members or stakeholders. With webhook integration, you can build custom workflows to fit your organization’s unique needs.

To set up alerts or scheduled exports:

1. An administrator must configure one or more destinations.

   For alerts, ensure the desired evaluation frequency is set.

   For webhook destinations, the administrator is responsible for processing the webhook’s JSON payload once it’s sent from GoodData.

2. Dashboard users can then open any dashboard and create alerts and scheduled exports using these destinations.

Create Destinations

As an administrator, you need to set up destinations to enable users to create alerts and scheduled exports. A destination can be either a webhook or an SMTP mail server. When triggered, GoodData sends a JSON payload to a webhook or an email to the email destination.

Create an Email Destination

When creating an email destination, you can choose between:

• Default SMTP server: Uses GoodData’s built-in email service
• Custom SMTP server: Configure your own SMTP server for delivery

You can also white-label the sender’s name and email address.

When a user creates an alert or scheduled export using an email destination, the selected SMTP server sends the email to the user’s email address as defined in user management.

Steps:

1. Go to Settings.

2. Under Destinations > Emails, click Create email.

   
   

3. Choose the SMTP server:

   For the default GoodData SMTP, the sender’s name and email address currently cannot be changed.

   
   

   For a custom SMTP server, provide the sender’s details, the SMTP server URL, and the necessary authentication credentials.

   
   

4. Once configured, click Create.

Create a Webhook Destination

GoodData can send alerts and export data as a JSON payload to a webhook destination. As an administrator, you are responsible for creating and managing these webhook destinations. For testing, you can use tools like webhook.site to capture and inspect HTTP requests, which simplifies the process of validating your webhook configurations before deploying them in production environments.

Steps:

1. Go to Settings.

2. Under Destinations > Webhooks, click Create webhook.

   
   

3. Configure the payload destination URL and, if necessary, provide a bearer authentication token. Click Create once everything is set up.

   
   

   The webhook destination is created.

Webhook Payloads

Alert payload example:

{
  "data": {
    "alert": {
      "condition": "greater than",
      "currentValue": 9.0,
      "metric": "Metric",
      "status": "SUCCESS",
      "threshold": 8.0
    },
    "details": {
      "subject": "Hello, World!"
    },
    "recipients": [
      {
        "email": "admin@gooddata.com",
        "id": "admin"
      },
      {
        "email": "tester@gooddata.com",
        "id": "tester"
      }
    ],
    "remainingActionCount": 10
  },
  "timestamp": "2024-09-03T14:34:40.263549Z",
  "type": "automation-task.completed"
}

Scheduled export payload example:

{
  "timestamp": "2024-08-01T15:12:41.689159286Z",
  "data": {
    "details": {
      "message": "Hello,\nthis is your scheduled export",
      "subject": "Test Schedule"
    },
    "visualExports": [
      {
        "exportId": "<export_id>",
        "status": "DONE",
        "fileUri": "<presigned_generated_url>",
        "traceId": "ec020036de43"
      }
    ],
    "automation": {
      "id": "<destination_id>",
      "title": "Webhook test",
      "dashboardURL": "<host_url>/dashboards/#/workspace/<workspace_id>/dashboard/<dashboard_id>"
    },
    "recipients": [
      {
        "email": "jane.doe@gooddata.com",
        "id": "<user_id>"
      }
    ],
    "remainingActionCount": 123
  },
  "type": "automation-task.completed"
}

Note that visualExports is used in case of a dashboard export, and tabularExports in case of a widget export.

Webhook Error Payloads

If an error occurs, we send an error payload.

Example of a failed alert:

{
  "data": {
    "alert": {
      "condition": "greater than",
      "metric": "Metric",
      "status": "ERROR",
      "traceId": "847839egf3a0695c"
    },
    "details": {
      "subject": "Hello, World!"
    },
    "recipients": [
      {
        "email": "admin@gooddata.com",
        "id": "admin"
      },
      {
        "email": "tester@gooddata.com",
        "id": "tester"
      }
    ],
    "remainingActionCount": 10
  },
  "timestamp": "2024-09-03T14:34:40.263549Z",
  "type": "automation-task.completed"
}

Example of a failed scheduled export:

{
  "data": {
    "details": {
      "title": "example"
    },
    "tabularExports": [
      {
        "exportId": "5a422124df0c1342543b95eacc5b_982638b2f84c3e7e5a7fc5d7955",
        "status": "ERROR",
        "errorMessage": "Export failed due to internal exception",
        "traceId": "134839eff3e9515c"
      },
      {
        "exportId": "5a422124df0c1342543b95eacc5b_dc30f52a8f04d299bcea726d1f5",
        "status": "ERROR",
        "errorMessage": "Export failed due to internal exception",
        "traceId": "134839eff3e9515c"
      }
    ]
  },
  "timestamp": "2024-07-08T08:38:22.123200127Z",
  "type": "automation-task.completed"
}

Note that visualExports is used in case of a dashboard export, and tabularExports in case of a widget export.

Evaluation Frequency

The evaluation frequency determines how often GoodData checks whether any alerts are triggered. You can configure this setting on the Settings page:

The frequency you set should align with or exceed your cache invalidation schedule. For example, if you set the evaluation frequency to hourly but refresh your data only once daily, alerts will be triggered at most once per day.

Create Alerts

Once destinations are created, users can create alerts by setting specific conditions and selecting a destination. Users need Workspace.ANALYZE permission for the workspace containing the dashboard to create alerts.

When triggered, alerts sent via email follow this format:

Webhook alerts send a JSON payload.

Steps:

1. Open a dashboard.

2. Hover over a widget, click the … button and select Alerts.

   
   

   The alert creation dialog opens.

3. Configure the alert’s condition, metric, and destination.

   
   

   Click the cogwheel button to configure the Trigger setting: The trigger can be set to send the alert every time alerts are evaluated, assuming its conditions are met, or trigger just once, after which the alert becomes paused.

   Once configured, click Create.

4. Edit, pause, or unpause existing alerts from the widget:

   
   

   or the dashboard-wide alert list:

   
   

Schedule Exports

Users can schedule exports by selecting a destination. Exports can send the dashboard or visualization as a PDF (or also XLSX for widgets) at scheduled intervals. Users need Workspace.ANALYZE permission for the workspace to schedule exports.

When triggered, export emails follow this format:

Webhook exports send a JSON payload.

Steps:

1. Open a dashboard.

2. In the top right corner, click the … button and select Schedule export.

   
   

   The scheduled export creation dialog opens.

3. Set the frequency, email recipients, and email content. Then click Create.

   
   

   Your automated PDF export is scheduled.

Export Widgets

The process for scheduling individual widgets is similar to dashboards. Click the … menu on the visualization and select Schedule export:

The dialog includes XLSX export options and the ability to disable merged attribute cells in XLSX exports:

For example, by default, an exported visualization in XLSX format might look like this:

If you disable the Keep attribute cells merged option, the XLSX table will look like this:

Filters

When creating a scheduled export, the active dashboard filters are saved as part of the scheduled export, and all exports will use those filter values. If you wish to disable this behavior, click the edited dashboard filters text and toggle Use default filters:

In this case, the default filters will be used. Note that if the dashboard’s default filter values are changed in the future, these new filter values will NOT be applied to this scheduled export.

Cron Expressions

For scheduled exports, you can define a custom schedule using a cron expression. GoodData supports a six-field UNIX cron format: second minute hour day month year. For example, the cron expression 0 0 15 ? * * will trigger the export daily at 15:00.

To create valid cron expressions, you can use online tools like the Free Formatter’s cron expression generator.