Skip to main content

Actions & Events

Actions and Events are used to interact with an embedded Cluvio dashboard from the outer application. 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"}
}

To navigate the embedded frame to another dashboard (i.e. another sharing link), use the navigate action. 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 by using postMessage to send a message to the outer application - 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. 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. The event has no parameters, for example:

{
  "event": "parametersReverted"
}

Sharing Secret Expired​

The secretExpired event is emitted when the sharing secret currently used by the embedded Cluvio dashboard expired and thus 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 report 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}
    ]
  }
}
Interactive Dashboards

This event is not sent from embedded interactive sharing links (i.e. with Allow Parameters enabled). Instead, the drill-down selection occurs directly inside the embedded dashboard.

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.