Initializing help system before first use

# Embedding Tableau Views with the vdl-tableau Component

Xpress Insight can embed Tableau worksheets and dashboards into the custom views of an app using the vdl-tableau component.

Insight exposes data in relational format to Tableau server based on the app configuration in the companion file. The dependencies declared by the vdl-tableau component cause Insight to prepare the required data. When the data is ready, the vdl-tableau component requests that Tableau query the data and render its visualization into the VDL view.

Tableau workbooks are included in the /tableau folder of the app archive and uploaded to Tableau Server automatically. Insight creates a "FICO Xpress Insight" project within the configured site (or the default site if no site has been configured in the server application.properties). Insight then creates a sub-project per app and uploads the app's workbooks to this location.

## Configuring the vdl-tableau component

The vdl-tableau component is available from the View Designer Palette in Xpress Workbench. It can also be directly added as code to the VDL source:

    <vdl-tableau
          mirror-tables="mirror_data_1,mirror_data_2,factory_supply_demand"
          workbook="vdl_language"
          view="Factories"
          height="270">
    </vdl-tableau>

The mirror-tables attribute is a comma-separated list of names matching those defined in the companion file. This attribute should be populated with the tables that the Tableau view requires to render.

The workbook attribute is the name of the Tableau workbook file (without file extension) containing the view to be embedded.

The view attribute is the case-sensitive name of the sheet or dashboard within the workbook.

The height attribute sets the height of the rendered Tableau view in pixels.

There are several other attributes available to configure the behaviour of the component. See the Javascript API Reference for more information.

## The lifecycle of the vdl-tableau component

The vdl-tableau component is a container for the Tableau view and will render that view when all the pre-requisites are met. It also communicates the state of the system when the view is not yet able to be displayed.

When the system is deploying a new mirror database, updating its schema, or publishing workbooks then the vdl-component displays a system status message:

When the required data is being expanded into the mirror database, the vdl-component shows the message "Preparing Data…" and a scrollbar with its value proportional to the completed effort to mirror the data:

When the component is waiting for the Tableau Embedding API to initialize and has been waiting for more than 2 seconds, the component shows a 100% progress bar and the message "Preparing Visualization..."

When the data that the view is dependent on is invalidated by a change, the component shows a placeholder message. This is most apparent when the scenario is executing, and the system is waiting for the new scenario data before it can begin updating the mirror.

When the workbook and view attributes are empty, the vdl-tableau component displays the selection id. This id is essential to the development of new Tableau views as the data need to be filtered by this id to select the correct set of scenario data for the view under development in Tableau Desktop.

Note: Note: A component will always display the selection_id if the Server environment type is "development" and the URL has "?debug=true" added. The component will not display the selection_id if the Insight Server environment type is set to "production".

## Positioning the Tableau component in a VDL view

By default, the Tableau visualization will display inline in the page content. You can control the height and width of the vdl-tableau component, or by default it will take the width of its container (for example a vdl-column of size 6 would be half the page). The default height is 400px, but you can change this to whatever suits your application. The example below sets the height of the vdl-tableau component to be 50vh, which is 50% of the overall view height (50vh).

    <vdl-tableau
          workbook="vdl_language"
          view="Factories"
          mirror-tables="mirror_data_1,mirror_data_2,factory_supply_demand"
          height="50vh"
          width="270px"
    ></vdl-tableau>

The component can also be configured to occupy the entire width and height of the Web Client view by adding the "vdl-tableau-full-page" class to the component.

    <vdl-tableau
          workbook="vdl_language"
          view="Factories"
          mirror-tables="factory_supply_demand"
          scenarios="=scenarios"
          class="vdl-tableau-full-page">
    </vdl-tableau>

## Including multiple Tableau components in a VDL view

Multiple vdl-tableau components can be included in the same view and there are no special considerations. The example below duplicates a Tableau visualization for each scenario on the shelf:

    <vdl-row vdl-repeat="=s,i in scenarios">
        <vdl-column size="10" heading="='Scenario: ' + s.props.name">
            <vdl-tableau workbook="vdl_language"
                         view="Factories"
                         scenarios="=i"
                         mirror-tables="mirror_data_1,mirror_data_2,factory_supply_demand"
                         height="270px"></vdl-tableau>
        </vdl-column>
    </vdl-row>

## Persisting and sharing visualization filter values between views

Tableau Global Filters are a feature provided by the Xpress Insight integration with Tableau. View developers can specify filters within a Tableau view as global. Global filter values are persisted per user between sessions, and applied to any other Tableau view that declares the same filter as global.

Global filters are declared with the global-filters attribute and consist of a comma separated list of Tableau filter names. Their values are stored in the local storage of the browser using the app id and user as their key. In cases where these need to be separated further within an app ( for example so two groups of Tableau view can have different values for the same filter), the storage-namespace attribute should be used to define a further element to add to the key.

There are some rules on what Tableau filters can be defined as global:

- Only String, Boolean and Numeric data types are supported. Tableau Global Filters using an unsupported data type will be ignored.
- Only categorical filters are supported. i.e., filters that are applied by selecting one or more values via a drop-down, radio button, check boxes or wildcard.
- When defining a Tableau Global Filter ensure that the selection criteria (single, multiple or wildcard) for the any displayed Tableau Quick Filter is the same for all views within the scope of the Tableau Global Filter. The Tableau Global Filter values are applied irrespective to the selection criteria of the Quick Filter as it is not possible for Xpress Insight to discover this from the view. For example on ViewA a Tableau Quick Filter is shown where a user can select multiple values. On ViewB the same Tableau Quick Filter is shown but the user can only select one value. If on ViewA the user changes the filtered values and selects multiple items and then moves to ViewB, the Tableau Quick Filter will only show one item selected in the Tableau Quick Filter but will filter based on the multiple items selected in ViewA.
- When defining a Tableau Global Filter ensure that any Tableau Quick Filters relating to a Tableau Global Filter shows all filter values and not just the filter values that relate to the data shown on the view. This is controlled via the Tableau 'Show More/Fewer' feature against a Quick Filter. As the Tableau Global Filter may act across several views it may cause confusion if a user cannot see exactly which filter values have been applied to the view.
- Care must be taken to avoid the situation where the combination of global filter values on one Tableau visualization eliminates those filter values as valid/available values for the global filters of another visualization on the same page. The system will not be able to achieve a consistent filter value across both visualizations.

Covered Topics

- Adding Tableau Parameters to a Custom View
  Tableau parameters are variables, such as a number, date, or string that can replace a constant value.
- Adding Tableau Global Filters to a Custom View
  Gloabl filters provide view developers with the means to specify filters within a Tableau view as global and therefore should be applied to other Tableau views (with the same or other workbooks) when the view is initialized.

Parent Topic Integrating Tableau Visualizations in Custom Views

© 2001-2026 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.