Setting up Events for Drilling in Embedded Analytical Designer and KPI Dashboards

GoodData portal supports several types of drilling:

  • You can configure reports so that when you click them, the reports drill to other reports, dashboards, or attributes. (For more information, see Drilling into Reports.)
  • In the embedded mode, you can set a drill event and integrate GoodData with a parent application. You can then drill from reports and insights directly to records outside of GoodData.

This article describes drill events and how they work on embedded KPI dashboards and in Analytical Designer.

For information about drill events for reports, see Embedded Dashboard and Report API - Events and Methods and Handle Drilling Report Requests through Your Web Application.

Contents:

Drillable Items

On embedded KPI dashboards and Analytical Designer, you can use postMessages to send a list of all measures and attributes that you want to be drillable for each insight, i.e. that you want to interact with your application.

Drillable items are then highlighted and clickable. You can then capture the events these measures and attributes fire and use them outside of the GoodData portal.

Enabling Drilling

  1. In your application, embed a KPI dashboard or Analytical Designer.
    For more information, see Embed a KPI Dashboard and Embed Analytical Designer.
  2. Add an event listener to the main windows object in your application and register the following:

    window.addEventListener('message', function(arg) { console.log(arg.data); });
  3. When the KPI dashboard or Analytical Designer loads, it sends a listeningForDrillableItems postMessage to your application.

    {
        "gdc": {
            "product": "dashboard", // or "analyticalDesigner"
            "event": {
                "name": "listeningForDrillableItems"
            }
        }
    }
  4. Your application sends back the list of URIs and/or identifiers of all measures and attribute display forms that should be drillable.
    The list must have the following format:

    {
        "gdc": {
            "product": "analyticalDesigner", // or "dashboard",
            "event": {
                "name": "drillableItems",
                "data": {
                    "uris": [
                        "/gdc/md/{projectHash}/obj/9211",
                        "/gdc/md/{projectHash}/obj/9212",
                        "/gdc/md/{projectHash}/obj/9213"
                    ],
                    "identifiers": [
                        "aaeb7jTCfexV",
                        "bbfc8kSDgfyW"
                    ],
                    "composedFrom": {
                        "uris": [
                            "/gdc/md/{projectHash}/obj/9214"
                        ],
                        "identifiers": [
                            "dugc2PfRgleE"
                        ],
                    }
                ]
            }
        }
    }

    All properties of the data entry are optional.

    You can use both display form URIs and identifiers to activate drilling.

    If a URI or an identifier from the list cannot be found on the dashboard or is invalid, this item is ignored.

    If a measure/attribute from the list does not become drillable, verify that their URI/identifier is correct.

    See also the How to Display Measure and Attribute URIs and Identifiers section.

    The composedFrom.uris and composedFrom.identifiers properties activate drilling for calculated measures created directly in Analytical Designer. Every identifier or uri in this property activates and every measure created from them is activated for drilling as well. For details about creating calculated measures, see Create Calculated Measures in Insights.

  5. To customize actions that happen when users click on a drillable item, follow instructions in the Capturing Events Sent from GoodData section.

See Drill Eventing versus Drill into Dashboard for additional details.

How to Display Measure and Attribute URIs and Identifiers

You can display the URI or identifier of each measure or attribute on the GoodData portal grey pages:

  1. In your browser, go to:
    For measures: https://{domain name}/gdc/md/{PROJECT_ID}/query/metrics
    For attributes: https://{domain name}/gdc/md/{PROJECT_ID}/query/attributes
  2. Click the measure/attribute whose identifier/URI you want to display.
  3. In the displayForms section, copy the display form identifier/URI.

Capturing Events Sent from GoodData

When a user clicks on a KPI/insight that is listed as a drillable item, a postMessage is sent to your application containing the following information:

  • The executionContext identifies the KPI/insight and is the same wherever in the KPI/insight users click.
  • The drillContext identifies the exact place where users click in an insight. It includes information about chart type, values, and so on.
  • The drillTo identifies the KPI's Drill into dashboard settings.
    For more information, see Drill Eventing versus Drill into Dashboard below.

To display the executionContext drillContext and drillTo :

  1. Add an event listener to your application.
    See step 2 in section Enabling Drilling.
  2. Open the browser developer tools.
  3. Click on an insight.

In the event listener in the MessageEvent section, search for the captured event executionContext, and  drillContext,and drillTo details in data.gdc.event.data.

Calculated measures created directly in Analytical Designer are not stored in the Data Catalogue and therefore they do not have uris or identifier. Drill events fired by clicking on such measures include only id and title, not  the header object.

For details about creating measures, see Create Calculated Measures in Insights.


 "executionContext": {
  "measures": [{
        "localIdentifier": "m1",
        "definition": {
            "measure": {
                "item": {
                    "uri": "/gdc/md/a1bc2defghi3jk4lmno56pqr7s8t9uvw/obj/9211"
                }
            }
        }
    }],
    "attributes": [{
            "localIdentifier": "a1",
            "displayForm": {
                "uri": "/gdc/md/a1bc2defghi3jk4lmno56pqr7s8t9uvw/obj/1027"
            }
        },
        {
            "localIdentifier": "a2",
            "displayForm": {
                "uri": "/gdc/md/a1bc2defghi3jk4lmno56pqr7s8t9uvw/obj/952"
            }
        }
    ],
    "filters": [{
        "negativeAttributeFilter": {
            "displayForm": {
                "uri": "/gdc/md/a1bc2defghi3jk4lmno56pqr7s8t9uvw/obj/952"
            },
            "notIn": [
                "/gdc/md/a1bc2defghi3jk4lmno56pqr7s8t9uvw/obj/951/elements?id=1",
                "/gdc/md/a1bc2defghi3jk4lmno56pqr7s8t9uvw/obj/951/elements?id=2",
                "/gdc/md/a1bc2defghi3jk4lmno56pqr7s8t9uvw/obj/951/elements?id=3",
                "/gdc/md/a1bc2defghi3jk4lmno56pqr7s8t9uvw/obj/951/elements?id=4"
      ]
    }
  ]
}

"drillContext": {
  "type": "pie",
  "element": "slice",
  "x": 1,
  "y": 40463,
  "intersection": [
    {
      "id": "1226",
      "title": "Direct Sales",
      "header": {
        "uri": "\/gdc\/md\/a1bc2defghi3jk4lmno56pqr7s8t9uvw\/obj\/1027",
        "identifier": "label.owner.department"
      }
    },
    {
      "id": "965523",
      "title": "WonderKid",
      "header": {
        "uri": "\/gdc\/md\/a1bc2defghi3jk4lmno56pqr7s8t9uvw\/obj\/952",
        "identifier": "label.product.id.name"
      }
    },
    {
      "id": "m1",
      "title": "_Close [BOP]",
      "header": {
        "uri": "\/gdc\/md\/a1bc2defghi3jk4lmno56pqr7s8t9uvw\/obj\/9211",
        "identifier": ""
      }
    }
  ]
}

Drill Eventing versus Drill into Dashboard

Insights on KPI dashboards may include the Drill into dashboard option (see Set up a KPI Dashboard).

By default, if your embed a KPI dashboard that includes insights with the Drill into dashboard set, the list of drillable items you send is ignored for these particular insights.

To override the Drill into dashboard and use your drilling settings, you must set the preventDefault URL parameter to true:

/dashboards/#/project/{projectHash}/dashboard/{dashboardID}?preventDefault=true

The table below shows how the preventDefault parameter affects the behavior when Drill into dashboard and/or drill eventing are enabled for an insight:

preventDefaultInsight with drill into dashboardInsight with drill eventingWhat is used

false

nothing
Drill into dashboard
Drill eventing
Drill into dashboard
truenothing
nothing
Drill eventing
Drill eventing

The preventDefault=true parameter does not delete the Drill into dashboard settings. You can find the settings in drillTo details contained in the postMessage sent to your application.

For details see Capturing Events Sent from GoodData.

Sample HTML Page

To see an example HTML page with drill eventing implementation, read Sample HTML for Drill Eventing.

Embedded KPI Dashboards with Navigation Panel Displayed

If you embed KPI dashboards, you can use the showNavigation=true to display the navigation panel with KPI dashboards. For details, see Embed a KPI Dashboard.

When you switch to another KPI dashboard, the list of  drillable items is lost. Your application must send a new list with drillable items after receiving the listeningForDrillableItems postMessage from GoodData.