Embedded Dashboard Events

Application State Events

You can use application state events to monitor changes in the application state, for example:

  • When the GoodData platform is down for maintenance, you can set a custom page to load when triggered by a notification of this event (in place of GoodData’s maintenance page).
  • When an error state renders a workspace inaccessible, you can display a custom error page.

The application loaded successfully

Event trigger: The application successfully loaded.

{
    gdc: {
        name: 'platform.info',
        type: 'app.ok'
    }
}

The report loaded successfully

Event trigger: The report successfully loaded.

{
    gdc: {
        name: 'report.info',
        type: 'app.ok'
    }
}

A user is active

Event trigger: A user is active in the embedded dashboard (listening to click and scroll events); the emit interval is 10 seconds.

{
    gdc: {
        name: 'ui.active',
        type: 'app.ok'
    }
}

A user has no access to a workspace

Event trigger: A user tries to access an embedded dashboard in a workspace that they do not have access rights to.

{
    gdc: {
        name: 'project.info.no.permission',
        type: 'app.ok'
    }
}

The frame size changed

Event trigger: The height of the content of the embedded dashboard changes, which happens when a tab is switched.

{
    gdc: {
        name: 'ui.frameinfo',
        type: 'app.ok'
        data: {
            height: {Number}, // pixel height of the contents
            width: {Number} // pixel width of the contents
        }
    }
}

Dashboard export initiated - embedded content started loading

Event trigger: The content of the embedded dashboard starts loading after a user chose to export to PDF the dashboard that hosts the embedded dashboard.

The dashboard export is paused until the content loading completes (the timeout is 30 seconds), which is indicated by the event ‘Dashboard export initiated - embedded content completed loading’.

gdc: {
    name: 'embedded.init',
    type: 'app.ok'
}

Dashboard export initiated - embedded content completed loading

Event trigger: The content of the embedded dashboard completes loading.

The dashboard export to PDF resumes, and the resulting PDF file is generated.

This event follows the event ‘Dashboard export initiated - embedded content started loading’.

gdc: {
    name: 'embedded.ready',
    type: 'app.ok'
}

Dashboard attribute and date filters changed

Event trigger: Attribute filters and date filters on the embedded dashboard (or the dashboard with embedded content) have changed.

See also: ‘Apply attribute and date filters to a dashboard’ in Embedded Dashboard Methods.

{
    gdc: {
        name: "filter.value.changed",
        type: "app.ok",
        data: [
            {
                label: "attribute.filter",
                type: "attribute",
                value: "attribute.value.1"
            },
            {
                label: "date.filter",
                type: "date",
                from: "2017-01-01", // (format: yyyy-mm-dd)
                to: "2017-12-31" // (format: yyyy-mm-dd)
            }
        ]
    }
}

The GDC_SELECT_ALL value for an attribute filter indicates that the filter is no longer applied to the dashboard (that is, all filter values are selected, which is similar to clicking Select all for an attribute filter in the GoodData Portal UI):

{
    gdc: {
        name: "filter.value.changed"
        type: "app.ok",
        data: [
            {
                label: "attribute.filter",
                type: "attribute",
                value: "GDC_SELECT_ALL"
            }
        ]
    }
}

Application servers are locked - maintenance

Event trigger: Application servers are locked for maintenance.

{
    gdc: {
        name: 'platform.maintenance',
        type: 'app.down'
    }
}

Application servers are locked - upgrade

Event trigger: Application servers are locked for upgrading to a new version.

{
    gdc: {
        name: 'platform.upgrade',
        type: 'app.down'
    }
}

A workspace is undergoing maintenance

Event trigger: The workspace is under maintenance.

{
    gdc: {
        name: 'project.maintenance',
        type: 'app.down',
        data: {
            projectUri: URISTRING
        }
    }
}

SST expired

Event trigger: The SuperSecure Token (SST) has expired.

{
    gdc: {
        name: 'sst.expired',
        type: 'app.ok'
    } 
}

A general error occurs

Event trigger: A general error occurs.

{
    gdc: {
        name: 'platform.error',
        type: 'app.down',
        data: {
            errorId: ID,
            errorCode: STRING
        }
    }
}

User Action Events

By default, all user actions are handled internally by the dashboard. You can override them by custom behavior.

  • Override the default behavior of a user action event  To override the default behavior of a user action event, list its name in the override parameter in the embedded code, for example:

    <iframe src="....&override=ui.link">

    You can specify multiple events in the URL. Separate individual event names by comma.

  • Force the default event behavior  To force the dashboard to handle a user action event using its default behavior, send the following message (ID must match the original action event ID):

    {
    gdc: {
        handleEvent: ID
    }
}

A user clicks a link - external window

Event trigger: A user clicks a link, which opens a page in an external window. For example, if you click a text link in a dashboard, it may trigger the opening of a new page in a new browser tab. This event is also triggered when a drill action on a report opens an external page.

{
    gdc: {
        name: 'ui.link',
        type: 'app.event',
        data: {
            uri: 'https://support.gooddata.com/'
        }
    }
}

A user drills into an embedded report or an embedded dashboard

Event trigger: A user clicks a value within an embedded report, or in a report in the embedded dashboard. This event can be passed to the parent web application. The parent web application detects:

  • The report and the report filters
  • The value that the user clicked
  • (For embedded dashboards only) The filters that were applied to the dashboard (on top of the report filters) at the moment when the user drilled into the report.

Based on the obtained information, the parent web application can build the target report with the data from your system. This way, the user can drill into the report in the context of their system’s data. This is especially useful for displaying the most granular data in the source application’s web user interface.

{ 
    gdc: {
        name: 'ui.drill',
        type: 'app.event',
        data: {
            executionContext: {...serializedExecutionContext},
            reportUri: URISTRING
        }
    }
}

where:

  • executionContext is the event execution parameters:
    • Metadata about the clicked value, such as what value was clicked (the value URI), the value type (attribute or metric), and others
    • (For embedded dashboards only) The filters that are applied to the dashboard
  • reportUri is the URI that points to the definition of the report that the user clicked. The report definition contains information on the report filters.

For more information on how to use this event, see Handle Drilling Report Requests through Your Web Application.

A user exports a report

Event trigger: A user clicks the button to export a report from the dashboard.

Make sure that you have listed the event name (report.export) in the override parameter in the embed URL.

{
    gdc: {
        eventId: ID,
        name: 'report.export',
        type: 'app.event',
        data: {
            reportUri: ..., % URI of the original report
            exportRequest: ...
        }
    }
}

where:

  • reportUri is the URI of the original report in the dashboard or the URI of the drill-across report that is to be exported.
  • exportRequest is the JSON of the report export request.

Example

The following is an example of the code that you can implement into your web application to manage event triggered by an embedded dashboard.

 

For this example, your iframe URL must be appended with the following:

&override=ui.link,report.export

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Parent app</title>
</head>
<body>
<iframe id="gooddata" src="https://secure.gooddata.com/dashboard.html#project={Project_URI}&dashboard={Dashboard_URI}&override=ui.link,report.export" width="100%" height="600px" frameborder="0"></iframe>
<script>
    // Initialize variables for the parent app and dashboard windows
    var dashboardWindow = document.getElementById('gooddata').contentWindow;
    var parentAppWindow = window;

    // Handles the application down events 
    function handleApplicationStateEventDown(message) {
        var reason;
        switch (message.name) {
            case 'platform.upgrade':
                reason = 'GoodData platform is being upgraded to a newer version';
                break;

            case 'platform.maintenance':
                reason = 'GoodData platform is under maintenance';
                break;

            case 'project.maintenance':
                reason = 'Project is under maintenance';
                break;

            case 'platform.error':
                default:
                reason = 'An error occurred while loading the GoodData application';
                break;
        }
        window.alert('Oh no, application is down ' + reason + '!', true);
    }

    // Handles user action events 
    function handleUserActionEvent(message) {
        switch(message.name) {
            case 'ui.link':
                window.alert('Handling click to link for ' + message.data.uri);
                break;

            case 'report.export':
                window.alert('Handling export of report ' + message.data.reportUri);
                break;
            default:
                window.alert('Unknown user action event');
                return;
        }

        // Change this to false if you want the event be handled by GoodData the default way
        var defaultHandling = true;

        if (defaultHandling) {
            var confirmMessage = {
                gdc: {
                    handleEvent: message.eventId
                }
            };

            dashboardWindow.postMessage(JSON.stringify(confirmMessage), '*');
        }
    }

    // Listen for messages in the parent app window
    parentAppWindow.addEventListener('message', function(e) {
        var message = JSON.parse(e.data);
        if (message.gdc) {
            message = message.gdc;

            switch (message.type) {
                case 'app.ok':
                    if (message.name == 'platform.info') window.alert('Application loaded successfully');
                    if (message.name == 'ui.active') window.alert('User activity');
                    if (message.name == 'ui.frameinfo') window.alert('Frame size changed, height:' + message.data.height);
                    break;

                case 'app.down':
                    handleApplicationStateEventDown(message);
                    break;

                case 'app.event':
                    handleUserActionEvent(message);
                    break;

                default:
                    window.alert('Unknown GoodData event');
            }
        }
    }, false);
</script>
</body>
</html>
Embedding Parameters
Embedded Dashboard Methods