Integrate Custom LWC in Dashboards with the Extensions SDK

Use custom Lightning Web Components (LWC) to facilitate complex tasks in your Tableau Next dashboards. The Dashboard Extensions SDK allows your custom components to interact directly with the data in your dashboards. Because these extensions inherit global dashboard styling and respond to filter updates, they provide a cohesive and native user experience.

This guide covers implementing and integrating custom LWCs into Tableau Next dashboards using the Component Widget framework.

• Install VS Code and configure it for Salesforce development. Use these Trailhead modules for installation and configuration:
  • Quick Start: Visual Studio Code for Salesforce Development
  • Quick Start: Lightning Web Components - Set Up Visual Studio Code
• Install the Salesforce CLI - Install Salesforce CLI

To build a custom LWC, follow the steps in Create a Hello World Lightning Web Component.

To make your custom LWC visible in the Tableau Next dashboard extension picker, your LWC must include the analytics__Dashboard target in the component metadata file.

1<targets>
2  <target>analytics__Dashboards</target>
3</targets>

Set the LWC display name and description for display in the extension picker.

1<masterLabel>My Custom Component</masterLabel>
2<description>A unique description for my custom component.</description>

Deploy your custom LWC into your org. Use the VS Code palette commands SFDX: Authorize an Org and SFDX: Deploy This Source to Org.

When your custom LWC is deploy to your org, you can add the component to your Tableau Next dashboard.

1. In Tableau Next, open your dashboard for editing.
2. Click the Extension icon and select an area of the dashboard.
3. Click Add Extension.
4. Select your custom component and click Select.
5. Set any properties for the component or to replace the existing component with another component on the widget panel.
6. Set the widget style on the design panel.

Pass dashboard filters, parameters, and state to your custom LWC using the Dashboard Extension SDK. This allows your LWC to interact with the data in your dashboard.

The Dashboard Extension SDK is the integration layer and secure boundary between the Tableau Next dashboard runtime and custom LWC. Extensions receive the SDK via DashboardWidgetComponentProps and use it to read dashboard context, subscribe to runtime events, and publish filters or parameters.

The SDK automatically added to the dashboard for each extension widget. In your component, the SDK is available as the sdk property passed with your widget properties. The constructor registers with the runtime so that when filters or parameters are applied elsewhere on the dashboard, the SDK emits FILTER_CHANGE and PARAMETER_CHANGE to your subscribers.

Retrieve the current dashboard context.

1@returns (Record<string, unknown>)
2getContext()

This method optionally takes the parameters:

• currentPage - (string) the name of the current dashboard page
• currentLayout - (string) the name of the current dashboard layout
• dashboardState.filters - (array) a list of the current semantic filters
• dashboardState.parameters - (array) a list of the current parameters

Use SDK_EVENTS to subscribe to dashboard runtime events.

on(eventName, handler) subscribes to an event. Returns a unsubscribe function.

off(eventName, handler) removes an event subscription.

1const SDK_EVENTS = {
2    FILTER_CHANGE: 'filterChange',
3    PARAMETER_CHANGE: 'parameterChange',
4};

FILTER_CHANGE and PARAMETER_CHANGE are fired internally when the runtime invokes the callbacks the SDK registered with the constructor, setApplyFilter and setApplyParameter.

Extension actions are available in sdk.actions.

applyFilter()

Publish a filter to the dashboard. sdk.actions.applyFilter(filter)

filter is an object with:

• fieldOrFields - string[] for a single field or string[][] for multiple fields
• values - string[] for a single value or string[][] for multiple values; for values for multiple fields, use an array of value tuples
• operator - string filter operator; defaults to In
• dataSourceName - string the optional data source name; defaults to the value from registerDataSource

applyParameter()

Publish a parameter for the dashboard to use in a query. sdk.actions.applyParameter(parameter)

parameter is an object with:

• name - string the parameter name
• value - string the parameter value
• datasourceName - string the optional data source name; Use dataSourceName or a registered data source.

notifyLifecycleChange()

Notifies when the lifecycle state of the component changes. sdk.actions.notifyLifecycleChange(eventName, details?)

eventName - string event name, valid values are:

• LIFE_CYCLE_EVENTS.INIT - component initializing
• LIFE_CYCLE_EVENTS.LOADED - component loaded successfully
• LIFE_CYCLE_EVENTS.ERROR - component is in an error state
• LIFE_CYCLE_EVENTS.NODATA - no data for the component

details - is an object with:

• message - string the optional event message
• error - string the optional error message

1enum LIFE_CYCLE_EVENTS {
2    INIT = 'init',
3    LOADED = 'loaded',
4    ERROR = 'error',
5    NO_DATA = 'nodata',
6}

This example shows how to use the Dashboard Extensions SDK in your component JavaScript.

1// In your extension component, define sdk prop as @api. 
2// Once extension component is connected, sdk will be available for use
3@api 
4sdk;
5
6// Register the data source, the semantic model name, your extension uses or pass dataSourceName on each filter/parameter
7connectedCallback() {
8    // React to filter changes
9    this.unsubscribe = this.sdk.on(SDK_EVENTS.FILTER_CHANGE, (filters) => {
10        // update your UI with filters
11    });
12}
13
14disconnectedCallback() {
15    // Clean up
16    this.unsubscribe();
17}
18
19// Get the dashboard context
20const { currentPage, dashboardState } = this.sdk.getContext();
21
22// Apply a single field filter from the extension to the dashboard
23this.sdk.actions.applyFilter({
24    fieldOrFields: 'Account.Type',
25    operator: 'In',
26    values: ['A', 'B'],
27    dataSourceName: 'myDataSDM'
28});
29
30// Apply a parameter
31this.sdk.actions.applyParameter({ name: 'Region', value: 'East', dataSourceName: 'myDataSDM' });
32
33// Report a loaded lifecycle event
34this.sdk.actions.notifyLifecycleChange(LIFE_CYCLE_EVENTS.LOADED);
35
36// Report an error lifecycle event with details
37this.sdk.actions.notifyLifecycleChange(LIFE_CYCLE_EVENTS.ERROR, { message: 'Load failed', error: err });

j

Get Started with Tableau Next Development

Tableau Next Features Overview

Tableau Next APIs and SDKs

Tableau Next Development Environments

Deploy Tableau Next Assets

Integrate Custom LWC in Dashboards with the Extensions SDK