Embed a Liveboard

Embed a Liveboard

This page explains how to embed a ThoughtSpot Liveboard in your Web page, portal, or application.

A ThoughtSpot Liveboard is an interactive dashboard that presents a collection of visualizations pinned by a user.

Import the LiveboardEmbed package🔗

Import the LiveboardEmbed SDK library to your application environment:

npm

import {
    LiveboardEmbed,
    AuthType,
    init,
    prefetch,
    EmbedEvent
}
from '@thoughtspot/visual-embed-sdk';

ES6

<script type = 'module'>
    import {
        LiveboardEmbed,
        AuthType,
        init,
        prefetch
    }
from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js';

Initialize the SDK🔗

Initialize the SDK and define authentication attributes.

Create an instance of the LiveboardEmbed class🔗

const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: '<%=liveboardGUID%>',
});

For more information about the Liveboard embed object, classes, methods, interface properties, and enumeration members, see the following pages:

Customize Liveboard view🔗

The second argument of the LiveboardEmbed() constructor is a LiveboardViewConfig object. This object includes several attributes and properties that are frequently used to customize the LiveboardEmbed component to fit within the embedding app’s UI experience.

The most common customization is controlling the visibility of menu items in the embedded view by configuring the disabledActions, hiddenActions, and visibleActions properties with an array of Action IDs. For information about the other frequently used properties, see common customization options.

Register, handle, and trigger events🔗

Register event listeners.

liveboardEmbed.on(EmbedEvent.init, showLoader)
liveboardEmbed.on(EmbedEvent.load, hideLoader)

For more information about events, see the following pages:

Render the embedded Liveboard🔗

Render the embedded Liveboard.

liveboardEmbed.render();

Verify the embedded object🔗

  1. Load the embedded object in your app. If the embedding is successful, you will see a Liveboard page with visualizations.

    Liveboard embed

  2. Explore the charts and tables, and verify if objects render and show the desired data.

Common customization options🔗

The LiveboardViewConfig object includes several properties and attributes that allow fine-grained control of the embedded experience. You can specify settings that enable or disable a specific feature, control visible or disabled menu elements and actions, set tabs and layout preferences, manage filters, hide header, and more.

Show/hide large UI elements🔗

Parameters such as hideLiveboardHeader, hideTabPanel, isLiveboardHeaderSticky, showLiveboardTitle, and showLiveboardDescription control various aspects of the standard embedded Liveboard experience. Note the phrasing of the property name and the description in the documentation to understand whether true enables or disables the particular feature.

LiveboardViewConfig parameters

The hideLiveboardHeader property removes the entire header area above the Liveboard, including filters and the overall Liveboard menu, which is a common pattern for "read-only' use cases or rebuilding your own menus and buttons using HostEvents.

The following constructor will disable the sticky header, while showing the Liveboard title, which would be hidden by default:

const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    isLiveboardHeaderSticky : false,
    showLiveboardTitle: true,
    liveboardId: '<%=liveboardGUID%>',
});
Note

When fullHeight is set to true, the SDK ignores the isLiveboardHeaderSticky:true setting, and the Liveboard header will not be sticky.

Customize Liveboard tabs🔗

By default, the first tab created on a Liveboard is set as the home tab. You can set any tab as an active tab using the activeTabId property in the Visual Embed SDK as shown in the example here:

const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8",
    activeTabId: "05406350-44ce-488e-abc5-5e8cdd65cf3c",
});
Note

The activeTabId property is available only in the LiveboardEmbed package and is not supported in the full application embed mode.

Reduce visible tabs and visualizations🔗

visibleVizs and visibleTabs allow for limiting the experience for certain users from a Liveboard with many more elements.

For example, a template Liveboard with many different KPIs could be reduced down to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization GUIDs as the array for visibleVizs on page load (there is an equivalent HostEvent called SetVisibleVizs to make an update after the Liveboard has loaded).

Add Note tiles🔗

You can add a Liveboard Note tile with custom text, images, and links on an embedded Liveboard.

  • Only users with edit access to a Liveboard can add a Note tile.

  • Users require Can upload data privilege to upload an image to the note tile.

  • If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see Security settings.

Redefine Liveboard breakpoint widths🔗

When turned on, the enable2ColumnLayout allows for customising the Liveboard breakpoint width for embedded users. The current 12 column layout changes to 2 columns per row at 1024px, and to 1 column per row layout at 630px in the new Liveboard experience. Once enabled, these breakpoints would apply to all Liveboards in the ThoughtSpot instance, and cannot be set only for individual Liveboards.

These breakpoint widths are customisable for the embedded customers. Contact ThoughtSpot support for assistance with customisation.

Customize filters🔗

To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. You can embed a Liveboard with filters already applied or define runtime filters in the Visual Embed SDK and apply filters during load time.

Embedding application users can also apply filters across visualizations using the cross-filter feature.

The Visual Embed SDK provides the following host events to trigger an action to get or update filters:

Date filters🔗

For DATE and DATE_TIME data types, you must provide the date and time values in the Epoch time format when applying or updating runtime filters via SDK or REST API.

However, when updating filters using HostEvent.UpdateFilters, you must include the date filter type along with the time period to apply any rolling or fixed time windows.

Note

For PERIOD filters, you must include the datePeriod attribute in the date filter object.

The following table lists the supported filter types and examples for each type:

TypeDescriptionExample

YESTERDAY

Specify the type as YESTERDAY.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        type: "YESTERDAY"
       }
   });

TODAY

Specify the type as TODAY.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        type: "TODAY"
       }
   });

TOMORROW

Specify the type as TOMORROW.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        type: "TOMORROW"
       }
   });

EXACT_DATE

Allows filtering column data to show details for the exact date, before or after the date. For example, to filter data for dates greater than 2023/07/31, specify 2023/07/31 as value, with the filter operator as GT.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "GT",
        values: ["2023-07-31"],
        type: "EXACT_DATE"
       }
   });

EXACT_DATE_RANGE

Specify the start date and end date in the values array. Ensure that the start date is lower than the end date. For example, "2023-01-31","2023-03-31".

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "BW_INC",
        values: ["2023-01-31","2023-03-31"],
        type: "EXACT_DATE_RANGE"
       }
   });

LAST_N_PERIOD

Specify the period. You must include the datePeriod attribute based on the time period specified in the filter object. Valid values for datePeriod are SECOND, MINUTE, HOUR, DAY, WEEK`, MONTH, QUARTER, and YEAR. For example, to filter column data by last 2 weeks, set datePeriod to WEEK and values to 2.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [2],
        datePeriod: "WEEK",
        type: "LAST_N_PERIOD"
      }
   });

NEXT_N_PERIOD

Specify the period. You must include the datePeriod attribute based on the time period specified in the filter object. Valid values for datePeriod are SECOND, MINUTE, HOUR, DAY, WEEK`, MONTH, QUARTER, and YEAR. For example, to filter column data by next 2 months, set datePeriod to MONTH and values to 2.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [2],
        datePeriod: "MONTH",
        type: "NEXT_N_PERIOD"
      }
   });

THIS_PERIOD

Specify the period. You must include the datePeriod attribute based on the time period specified in the filter object. Valid values for datePeriod are SECOND, MINUTE, HOUR, DAY, WEEK`, MONTH, QUARTER, and YEAR.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        datePeriod: "MONTH",
        type: "THIS_PERIOD"
      }
   });

PERIOD_TO_DATE

Specify the period. You must include the datePeriod attribute based on the time period specified in the filter object. Valid values for datePeriod are WEEK, MONTH, QUARTER, and YEAR.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        datePeriod: "QUARTER",
        type: "PERIOD_TO_DATE"
      }
   });

YEAR_ONLY

Specify the year. For example, 2023.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: ["2023"],
        type: "YEAR_ONLY"
      }
   });

MONTH_YEAR

Specify the month and year in the values array. For example, "July","2023".

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: ["July","2023"],
        type: "MONTH_YEAR"
      }
   });

QUARTER_YEAR

Specify the quarter and year in the values array. For example, "Q1","2023".

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: ["Q1","2023"],
        type: "QUARTER_YEAR"
      }
   });

Customize filter visibility in Liveboard tabs🔗

Filters and parameters that are not relevant to the visualizations in a tab can be hidden by default on an embedded Liveboard. This feature is disabled by default on ThoughtSpot embedded instances. To enable this feature, set hideIrrelevantChipsInLiveboardTabs to true.

Note

This feature is supported only if compact header is enabled on your Liveboard. To enable compact header, use the isLiveboardCompactHeaderEnabled attribute.

const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: '<%=liveboardGUID%>', // Replace it with your Liveboard ID
    isLiveboardCompactHeaderEnabled: true,
    hideIrrelevantChipsInLiveboardTabs: true,
    // ... other embed view configuration settings
});

Liveboard comments🔗

ThoughtSpot does not support adding comments, replying, or subscribing to comment threads on embedded Liveboards.

Additional resources🔗