In this article, we'd like to show how you could quite easily set up drillthrough when embedding Luzmo dashboards, to further extend the interactivity of your meaningful insights. This could allow you to visualize the most important high-level KPIs in one dashboard, which contains actionable widgets that enable your end-users to dive into more details about a specific data point 🎯

What is drillthrough?

Drillthrough allows users to navigate from summary insights in one dashboard, to detailed information in another dashboard. This empowers end-users to explore specific data points in greater detail, enhancing their ability to derive meaningful insights and make informed decisions. You can see an example implementation in the video below!

Overview

Here you can find the required steps to set up drillthrough dashboards in your application:

• Initial setup in Luzmo: you should design at least two meaningful "main" and "drillthrough" dashboards to allow your end-users to digest both high-level and lower-level insights.
  In your "main" dashboard, you should set up a Custom event in a widget to allow your end-users to trigger a drillthrough action in you application. In your "drillthrough" dashboard, you should visualize lower-level insights on the drill through category that users can dive into. Make sure to set up parameterized filters to dynamically display details based on user interactions in the previous dashboard.

• Initial setup in your application frontend: when embedding your "main" dashboard, you should set up a 'Custom events' event listener. Next to that, when a custom event is emitted, you should parse the desired data from the Custom event's payload to set up the desired drillthrough filtering. Last but not least, your frontend should send a request to your backend to provide an embed authorization token that dynamically filters to the selected data point, and you can then use this new embed token to embed the drillthrough dashboard (in e.g. a modal).

• Initial setup in your application backend: your frontend should be able to request embed authorization tokens with additional parameter overrides from your backend, to allow the frontend code to dynamically pass along the selected value from the "main" dashboard to the "drillthrough" dashboard.

Initial setup in Luzmo

As mentioned earlier, you want to enable the user to see more details on the element they clicked on when looking at the "drillthrough" dashboard. To do so, you will need to embed the "main" dashboard first, and upon a custom action you want to load the "drillthrough" dashboard with the parameter filter set to the value the user clicked on.

Define a Custom event in a widget of your main dashboard

The first step to set up drillthrough from a specific widget, is to visit the widget's settings and enable Custom events (under the "Interactivity" section). This will ensure that clicks on data points visualized within the widget can trigger a custom action in your application, when the dashboard is embedded. In this case, the custom action implemented is expected to open a second "drillthrough" dashboard, filtered to the item the user clicked on.
This Academy article provides more information about custom events and how to set them up!

Design a meaningful drillthrough dashboard

Next to the initial dashboard, you should of course also create the desired dashboard to drill through to. In this dashboard, you should visualize meaningful lower level insights, to ensure your end-users can easily digest the details of the data point selected in the initial dashboard!

The easiest way to ensure the user will see the info of the selected data point when drilling down to the "drillthrough" dashboard is by setting up a parameter filter on it. You will fill in the value of the parameter filter dynamically upon the custom event triggering.

In the dashboard filters, you should set up a parameterized filter on the column you'd like to drill through to; this allows you to get a more representative view that is similar to how an end-user would see the dashboard when building it (as it's filtered by the default parameter value), while your application can dynamically override the parameter value when drilling through to this dashboard (see "Step 3.4" below).

Initial setup in your application

Below you can find the different steps that your application needs to take care off to properly set up drillthrough dashboards. Sme examples below refer to a bar chart that shows aggregated data by marketing campaign, which includes a Custom event that should drill through to another dashboard. You could of course set this up on any dashboard widget that contains a "Custom events" implementation.

Step 1: Embed your "main" dashboard

To kick things off, it's of course important to first visualize high-level insights to your end-users, which they can easily digest. This means you'll want to embed your "main" dashboard in your frontend using our embed Authorization mechanism: in case you'd like to dive into more information, take a look at this Academy course!

Step 2: Set up a Custom event listener in your frontend

When a Custom Event is emitted by the frontend component, your application should read the payload of the event to know which data point was selected by your end-user. As a first step, you should thus set up an event listener in your frontend to listen to the Custom events that the Luzmo component emits each time a user triggers a custom event in an embedded dashboard.

document.querySelector('LuzmoDashboardComponent').addEventListener(
  'customEvent', 
  (customEventPayload) => {
    /* Read out event payload */
  }
);

Step 3: Read out the selected data point from the payload of the Custom event

To get the appropriate data to filter on, you should parse the payload of the custom event (e.g. the "category" slot of the bar chart, in order to get the "Marketing campaign" the end-user clicked on).Based on the Custom event name and the payload, your application should take specific actions.
Learn more about the structure of the event payload in our Developer documentation.

...
(customEventPayload) => {
  const eventData = customEventPayload.data.data;
    
  // Check if the custom event is the drillthrough event you set up in the dashboard
  if (eventData.event = "campaign_drillthrough") {
    // Name of the parameter set up in the drillthrough dashboard
    const drillthroughParameterToOverride = "marketingCampaign";
    
    // Read out the data value from the appropriate widget slot
    const parameterValueToFilterOn = eventData.category.id;
  }
  ... // Other custom event handlers
});

Reading out other filters from the dashboard to apply on the drillthrough dashboard

Do you want to read out active filters from the dashboard to apply these to the drillthrough dashboard as well? Check out this article which explains how to:

1. get active filters from a dashboard
2. translate these to initialization filters.
3. and embed a dashboard with initialization filters.

A key difference in step 2 between drillthrough (what we cover in this article) and the use case in the article referenced "Loading a dashboard in the same filter state as a user left it" is that with drillthrough you want to load a different dashboard, while in the article the same dashboard is being loaded.

With drillthrough, you have two options:

1. Read out the active filters on dashboard 1 and set them as initialization filters on dashboard 2. For this, you will need to create & mantain a mapping file to know which charts from dashboard 1 match with which charts on dashboard 2.
2. Apply the read out filters from dashboard 1 as "global filters" on dashboard 2. These global filters are static in the sense that the user will not be able to change them. See this example in our developer docs on how to add a global filter to the embed token.

Step 4: Request a new embed authorization token from your application's backend

You should make sure to pass along the desired values to filter the drillthrough dashboard to (e.g. the selected "Marketing campaign").
Note that the example method getAuthorizationTokenFromBackend below is part of the example application: this method will make a request to the application's backend to retrieve an embed Authorization request (see "Step 3.4" below).

...
(customEventPayload) => {
  ...
  // Retrieve a new embed Authorization token from the backend,
  // with the additional drillthrough parameter override(s).
  const {embedKey, embedToken} = getAuthorizationTokenFromBackend(
    drillthroughParameterToOverride, 
    parameterValueToFilterOn
  );
	...
});

Step 5: Override the parameter value in the embed authorization request

In your application's backend, you should add the specific values (e.g. the "Marketing campaign" that was clicked on) passed along by the frontend as parameter overrides. Do make sure that any multi-tenant parameters are always correctly applied after specifying the drillthrough parameter overrides!
You can refer to this Academy article for more information about our Parameter functionality.

POST https://api.luzmo.com/0.1.0/authorization
{
  "action":"create",
  "version":"0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties":{
    "type": "embed",
    ...
    "parameter_overrides": {
      "< drillthrough parameter name >": ["< drillthrough filter value to apply >"]
    }
  }
}
EOF

Step 6: Embed the drillthrough dashboard with the new embed token

The frontend application can now embed the drillthrough dashboard using the new embed authorization token, which you can embed in your application in the desired manner (e.g. in a modal).
Note that the example method openDrillThroughDashboardInModal below is part of the example application: it opens a modal of the application, and uses the Embed key and token to embed the specified drill through dashboard in there!

...
(customEventPayload) => {
  ... 
  // Use the new embed key and token to embed a specific dashboard, in e.g. a modal
  openDrillThroughDashboardInModal("drillthroughDashboardId", embedKey, embedToken);
});

Full frontend code example

Below you can see the minimalistic implementation of the separate code snippets above:

document.querySelector('LuzmoDashboardComponent').addEventListener(
  'customEvent', 
  (customEventPayload) => {
    const eventData = customEventPayload.data.data;
    
    // Check if the custom event is the drillthrough event you set up in the dashboard
    if (eventData.event = "campaign_drillthrough") {
      // Name of the parameter set up in the drillthrough dashboard
      const drillthroughParameterToOverride = "marketingCampaign";

      // Read out the data value from the appropriate widget slot
      const parameterValueToFilterOn = eventData.category.id;

    // Retrieve a new embed Authorization token with the additional drillthrough parameter override(s)
    const {embedKey, embedToken} = getAuthorizationTokenFromBackend(
      drillthroughParameterToOverride, 
      parameterValueToFilterOn
    );

    // Use the new embed key and token to embed a specific dashboard, in e.g. a modal
    openDrillThroughDashboardInModal("drillthroughDashboardId", embedKey, embedToken);
  }
});

Conclusion

By following these steps, you can create a powerful and user-friendly drillthrough setup in your application using Luzmo's Custom Events functionality. This will enable your end-users to explore data in a more interactive and personalized way.