Actions & Events

Actions and Events are used to interact with an embedded Cluvio dashboard from the outer application via JavaScript. Your application can send actions to the embedded Cluvio application to forward user input received through your own UI or to react to events received from the embedded dashboard. Your application can in turn receive events to react to changes in the embedded Cluvio application.

Actions

All actions are sent via window.postMessage to the embedded Cluvio window. The JSON message format for all actions is

{
  "action": "<name-of-action>",
  "params": { <params-of-action> }
}

whereby <params-of-action> is a JSON object with action-specific parameters.

Target Origin

Use https://dashboards.cluvio.com as the targetOrigin parameter to postMessage.

Change Parameters

To change dashboard filter parameters, use the action changeParameters.

The parameters aggregation and timerange are used for the built-in aggregation and built-in timerange filters.

For example:

{
  "action": "changeParameters",
  "params": {"aggregation": "week", "timerange": "1686838280~1686838380"}
}

Parameters for custom filters must be grouped together in the filters parameter. For example:

{
  "action": "changeParameters",
  "params": {"filters": {"my_filter_a": "some value", "my_filter_b": 42}}
}

Download Image

To trigger an image download on the embedded dashboard or a single report, use the action downloadImage. The only optional parameter is a reportId, which must be a JSON string with the targeted Cluvio report ID.

For example, to trigger a dashboard image download:

{
  "action": "downloadImage"
}

To trigger a report image download:

{
  "action": "downloadImage",
  "reportId": "vqkp-z5wz-oy56"
}

Download PDF

To trigger a PDF download on the embedded dashboard or a single report, use the action downloadPdf. The only optional parameter is a reportId, which must be a JSON string with the targeted Cluvio report ID.

For example, to trigger a dashboard PDF download:

{
  "action": "downloadPdf"
}

To trigger a report PDF download:

{
  "action": "downloadPdf",
  "params": {"reportId": "vqkp-z5wz-oy56"}
}

Download Excel Sheets

To trigger an Excel download on the embedded dashboard or a single report, use the action downloadExcel. The only optional parameter is a reportId, which must be a JSON string with the targeted Cluvio report ID.

For example, to trigger a dashboard Excel download:

{
  "action": "downloadExcel"
}

To trigger a report PDF download:

{
  "action": "downloadExcel",
  "params": {"reportId": "vqkp-z5wz-oy56"}
}

Navigate

To navigate the embedded frame to another dashboard (i.e. another sharing link), use the navigate action with the dashboardId and sharingToken parameters. For example:

{
  "action": "navigate",
  "params": {
    "dashboardId": "1qk7-yrly-0vzd",
    "sharingToken": "ebc1c3ed-340b-4053-98e0-38b0fc6fb5de"
  }
}

If the target sharing link requires the use of a sharingSecret, it must also be provided as a parameter.

Refresh Dashboard

To explicitly refresh the data on a dashboard, use the refresh action without parameters. For example:

{
  "action": "refresh"
}

Show Report

To show a single maximised report in the embedded dashboard, use the action showReport. The only required parameter is a reportId, which must be a JSON string with the targeted Cluvio report ID. For example:

{
  "action": "showReport",
  "params": {"reportId": "vqkp-z5wz-oy56"}
}

Show Dashboard

To revert back to showing the full dashboard, e.g. after using showReport earlier, use the showDashboard action without parameters. For example:

{
  "action": "showDashboard"
}

Update Dashboard Settings

The updateSettings action can be used to update some dashboard settings. At the moment, the only available setting in this action is darkMode, which can be used to turn "dark mode" (i.e. night-time color scheme) on or off. For example, to turn dark mode on:

{
  "action": "updateSettings",
  "params": {
    "darkMode": true
  }
}

To turn dark mode off:

{
  "action": "updateSettings",
  "params": {
    "darkMode": false
  }
}

Update Sharing Secret

To update the sharingSecret parameter used by an embedded dashboard, e.g. because it is about to expire or to update the fixed_parameters, use the updateSharingSecret action:

{
  "action": "updateSharingSecret",
  "params": {
    "sharingSecret": "<JWT>"
  }
}

Events

The embedded Cluvio application emits events via postMessage to the outer window element - you can listen to these in your JavaScript code to respond to changes, such as refreshing an expired sharing secret or updating the state of your own filter controls to reflect the changes that happened on the embedded dashboard. The message format for all events is

{
  "event": "<name-of-event>",
  "params": { <params-of-event> }
}

whereby <params-of-event> is a JSON object with event-specific parameters.

Parameters Changed

The parametersChanged event is emitted when the Cluvio filter bar is updated with new values on an interactive sharing link. The new filter parameter values are included in the parameters field. For example:

{
  "event": "parametersChanged",
  "params": {
    "parameters": {
      "aggregation":"week",
      "timerange":"1467331200~1483228799",
      "filters": [
        { "filter_name": "my_country_filter", "selected_values": ["Germany"] }
      ]
    }
  }
}

Parameters Reverted

The parametersReverted event is emitted when Revert to Defaults is selected in the Cluvio filter bar on an interactive sharing link. The event has no parameters. For example:

{
  "event": "parametersReverted"
}

Sharing Secret Expired

The secretExpired event is emitted when the sharing link requires a sharing secret and the current sharing secret used by the embedded Cluvio dashboard expired and should be regenerated (see also updateSharingSecret). The event has no parameters. For example:

{
  "event": "secretExpired"
}

Embed Size Changed

The embedSize event is emitted when the embedded Cluvio dashboard is initially rendered and subsequently whenever it is resized, usually by new reports appearing or reports being removed. Your application can react by adjusting the iframe DOM element size based on the actual dimensions the embedded dashboard needs. The typical case is having a width of the iframe determined by the available space and a dynamic height based on the needs of the dashboard grid. The event has two parameters, width and height, for example:

{
  "event": "embedSize",
  "params": {
    "width": 1200,
    "height": 800
  }
}

Drill-Down Selection

The drillSelect event is emitted when the user clicks on a drill-down link in a chart of an embedded non-interactive dashboard configured with the same dashboard as the drill-down target. The filters parameter contains a list of the drill-down filters and their corresponding values. For example:

{
  "event": "drillSelect",
  "params": {
    "filters": [
        {"filterVariable": "my_filter", "value": 42}
    ]
  }
}

Conditional Event

This event is only emitted when the enableDrillEvents URL parameter is included on a non-interactive sharing link. It is never emitted for interactive sharing links (Allow Parameters enabled), where drill-down actions targeting the same dashboard are performed automatically.

Drill-Down Navigation

The drillDown event is emitted when the user clicks on a drill-down link configured with a different dashboard as the drill-down target. The dashboardId parameter contains the target dashboard ID and the filters parameter contains the list of drill-down filter values. For example:

{
  "event": "drillSelect",
  "params": {
    "dashboardId": "1qk7-yrly-0vzd",
    "filters": [
        {"filterVariable": "my_filter", "value": 42}
    ]
  }
}

Your application can react e.g. by sending the navigate action to the Cluvio embed.

Conditional Event

This event is only emitted when the enableDrillEvents URL parameter is included on a sharing link.