Embed a Liveboard

Table of Contents

Import the LiveboardEmbed package
Initialize the SDK
Create an instance of the LiveboardEmbed class
Define a method to process callback custom actions payload
Register, handle, and trigger events
Render the embedded Liveboard
Test the embedded workflow
Additional resources

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

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';javascript

ES6

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

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%',
    },
    disabledActions: [],
    fullHeight: true,
    disabledActionReason: '<reason for disabling>',
    hiddenActions: [],
    liveboardId: '<%=liveboardGUID%>',
    enableVizTransformations: true,
    preventLiveboardFilterRemoval: true,
    visibleVizs: []
    runtimeFilters: [],
});JavaScript

frameParams: Sets the width and height dimensions to render the Liveboard object. You can set the width and height attribute values in pixels or as a percentage.

fullHeight Optional: Boolean. Dynamically resizes the embedded Liveboard frame according to the height of the Liveboard.

If the embedded Liveboard does not fit vertically within your application page, a second scroll bar may appear. When fullHeight is set to true, the embedded Liveboard frame is automatically adjusted according to the height of the Liveboard, and the second scroll bar does not appear.
defaultHeight: Integer. Minimum height to set for embedded objects on a Liveboard page and the corresponding visualization pages that a user can navigate to from the Liveboard page. The default value is 500 pixels.
Try it out

visibleActions Optional

Array of strings. Displays the specified actions on the Liveboards page. These actions can appear as buttons, or as menu actions in More or the contextual menu. You can use this attribute to show a small subset of actions from the list of available actions.

visibleActions: [Action.DownloadAsPDF,Action.DownloadAsCSV,Action.Save,Action.Present]

Try it out

Note	Use either `visibleActions` or `hiddenActions` to show or hide the actions in the embedded UI. For more information, see Show or hide UI actions.

hiddenActions Optional

Array of strings. Hides specified actions from the list of available actions on the embedded Liveboards page. You can use this attribute to remove the actions that are not relevant to your application context. Do not use this attribute if visibleActions are defined.

For example, to hide Add filters action from the More menu , specify Action.AddFilter in the hiddenActions attribute.

hiddenActions: [Action.AddFilter]

Try it out

disabledActions Optional

Array of strings. Disables the specified actions. You can use this attribute to restrict user access to certain features.

For example, to disable the Present action from the More menu , specify Action.Present in the disabledActions attribute.

disabledActions: [Action.Present]

Try it out

Note

ThoughtSpot automatically creates a modifiable action ID based on the name you assign to a custom action. For example, if you set the name of a custom action as Send Email, ThoughtSpot sets the ID for this action as send-email by default. To disable, hide, or show a custom action in the embedded UI, you must specify the ID of the custom action as the action string in the disabledActions, hiddenActions, and visibleActions attributes.

disabledActionReason Optional: String. The text to show for disabled actions. The text string specified in disabledActionReason shows as a tooltip when a user hovers over a disabled action in the embedded UI. For example, if you have disabled the Download action and you intend to enable this action for only authorized users, you can specify disabledActionReason as Contact your administrator to enable this feature.
liveboardId: String. The GUID of the Liveboard.
enableVizTransformations Optional: Boolean. When set to true, it displays the contextual menu for visualizations. The contextual menu allows users to drill down a visualization, apply filters, and view detailed insights.

preventLiveboardFilterRemoval Optional

Boolean. When set to true, it disables the filter removal action and thus prevents users from removing the filters applied to a Liveboard visualization.

visibleVizs Optional

Array of strings. Allows adding GUIDs of the visualizations, which you want to show by default on an embedded Liveboard when it renders for the first time.

You can show or hide the visualizations by triggering the SetVisibleVizs event.

runtimeFilters optional

Runtime filters to apply when the pinboard page loads. Runtime filters provide the ability to filter data at the time of retrieval. Runtime filters allow you to apply a filter to a visualization in a pinboard by passing filter specifications as URL query parameters.

Runtime filters do not appear to the user in the Liveboard UI. They do not adjust the values of visible Liveboard filters, but act as an additional set of filters — both runtime filters and UI filters will be applied within the queries.

For example, to sort values equal to red in the Color column for a visualization in a Liveboard, you can pass the runtime filter in the URL query parameters as shown here:

runtimeFilters: [{
    columnName: 'Region',
    operator: RuntimeFilterOp.IN,
    values: ['Midwest', 'East', 'West']
}]javascript

columnName: String. Name of the column to filter by.
operator: String. The runtime filter operator. For more information about the runtime filter operators, see Runtime filters.
values: String, Integer, or Boolean. The list of operands. Operators like EQ, LE accept a single operand, whereas other operators like BW and IN accept multiple operands.

Try it out

For more information about the supported data types and how to use runtime filters, see Runtime filters.

Define a method to process callback custom actions payload🔗

If your application instance requires callback custom actions to retrieve large data sets in answer payload, define a method to process data in batches and paginate the response.

.on(EmbedEvent.CustomAction, async(payload: any) => {
	const data = payload.data;
	if(data.id === 'insert custom action ID') {
		const fetchAnswerData = await payload.answerService.fetchData(offset, batchSize);
		console.log('fetchAnswerData:::', fetchAnswerData);
	}
})javascript

offset: Integer. Sets the starting point for the records retrieved from the search answer. For example, if you want to retrieve the initial set of records in 3 batches, set the value to 0.
batchSize: Integer. Divides the data set into batches. For example, if you specify the batchSize as 3, the three batches are processed independently for faster response.

If the dataset is divided into 10 batches, and the offset value is 0 and the batchSize is 3, the first three batches of the dataset are retrieved in the answer payload in one UI query. Similarly, if the offset value is 1 and the batchSize is 3, the next set of batches (4,5, and 6) are retrieved.

Register, handle, and trigger events🔗

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

For more information, see Interact with events.

Render the embedded Liveboard🔗

Render the embedded Liveboard.

liveboardEmbed.render();JavaScript

Test the embedded workflow🔗

Load the client application.
Try accessing a Liveboard embedded in your application.
Verify if the embedded content renders correctly on your application page.
If you have disabled an action, verify if the action appears as disabled on the Liveboards page.
If runtime filters are configured, verify if the filters are applied to the visualizations on the Liveboard.

Additional resources🔗

For code examples, see Code samples.
For more information about the SDK APIs and attributes, see Visual Embed SDK Reference.

On this page

Table of Contents

Import the LiveboardEmbed package
Initialize the SDK
Create an instance of the LiveboardEmbed class
Define a method to process callback custom actions payload
Register, handle, and trigger events
Render the embedded Liveboard
Test the embedded workflow
Additional resources