Initializing help system before first use

Tutorial: Building your First Tableau View

This tutorial demonstrates the end-to-end process for developing a view that embeds a Tableau visualization. The tutorial adds a view to the Xpress Workbench 'new project' template. The view includes a visualization of the template input array, across multiple scenarios, as a bar chart.
The tutorial has the following pre-requisites:

  • A development installation of Insight 5.4 or later which has been integrated with Tableau Server. See Integrating Xpress Insight with Tableau for more information.

  • An installation of Workbench 3.7 or later for editing the app project.
  • An installation of Tableau Desktop for authoring a Tableau workbook.
  • User accounts for Insight and Tableau Server with matching usernames.
  • A working knowledge of Insight app development and deployment.
  • A basic knowledge of Tableau authoring. Learning material can be found in Learning area of
This tutorial includes information on each step of adding a Tableau visualization to an Xpress Insightview, including:
  • Defining the data for the visualization
  • Adding the Tableau VDL component to the view
  • Creating the Tableau workbook
  • Designing the visualization
  • Completing the view
Defining the Data for the Visualization
  1. Open Xpress Workbench and create a new Mosel or Python Insight project.

  2. Open the app's companion file and add the following block of XML config above the <client> tag to configure what data is exposed to Tableau in the Mirror. 
    <database-mirror>
    <mirror-tables>
        <mirror-table name="table1">
            <entity name="Input" />
        </mirror-table>
    </mirror-tables>
</database-mirror>
    The mirror database is the source of scenario data used for visualizations. This config defines a database table called table1 which is populated with the input entity data (the indices index set is included implicitly). See Configuring How Data is Exposed to BI Software for more information.
Adding the Tableau VDL Component
  1. In Xpress Workbench, select File > New > Insight View (VDL) to add a new VDL view.
    For the purposes of this tutorial, the default values for the fields are suitable.
  2. Add a Tableau component to the new view by dragging the Tableau component from the palette into a column element.
    This component embeds a Tableau visualization that will be created later.

  3. Set the mirror-tables attribute to table1 in the Attributes panel to declare the mirror table that this Tableau component requires for rendering the visualization.
    The value must match the name of the table declared in Step 2.
  4. Set the scenarios attribute to =scenarios to specify that this Tableau visualization will show the data from all scenarios on the shelf.
    A value of =0 would show data from only the first scenario.
  5. Publish the app to Xpress Insight.
  6. Open the new view in the published app. Place at least two loaded scenarios on the shelf.
    The data from these scenarios is used during the development of the Tableau workbook.
  7. The Tableau component will display an id. This is the selection id. The component displays this id when it is not yet configured with a workbook and view. The id will be used to filter the data in Tableau desktop to only the data relating to the scenarios we have selected on the shelf. You will need the selection id later in this tutorial. Leave this Insight view open in the browser. The data will be cached in the mirror database and available to Tableau Desktop for as long as the view is open.

Creating the Tableau Workbook
  1. Open Tableau Desktop and click File > New to create a new Tableau workbook.
  2. Click on Data > New Data Source, then choose MySQL as shown below. MySQL is used as a data connection between the Tableau workbook and the mirror database.

  3. Tableau Desktop needs the app-specific credentials of the mirror database to access the scenario data. This information is available from the user interface in Insight. In the app, go to the cogs menu next to the shelf and choose the Mirror Database option.

  4. Copy the mirror database connection properties from the Insight dialog to the Tableau Desktop MySQL connection dialog.

  5. Define a data source which uses the scenario data tables required by the workbook design. Any data tables must be joined to the insight_selection table to select the correct data. Drag the insight_selection table onto the canvas and double-click on the insight_selection box. Drag table1 and place it to the side (not on top) of the insight_selection box. The tables are now joined and should appear as shown below:

    Important: Do not connect the tables on the first logical layer using a relationship. It is important to double-click on the insight_selection box and then create a physical join for performance reasons. See The Tableau Data Model.
  6. The data source requires a filter on username to implement the Insight user access model. This ensures that the currently authenticated username must match the username of the Tableau view requestor. In the top-right of the Tableau Desktop interface, click on Add under the filters caption. Click Add again on the Edit Data Source Filters dialog. Select username from the list. Switch to the Conditions tab and select by formula and enter [Username]=username(). Click OK to close the dialogs.

  7. Now that the workbook is secured by the username filter, Tableau Desktop will need to supply your authenticated username to the workbook data source. In Tableau Desktop select Server > Sign In from the menu. Enter the Tableau Server URL and click Connect. In the browser window that opens, enter your Tableau Server username and password. Close the browser window and return to Tableau Desktop.
Designing the Visualization
  1. Click on Sheet 1 in the bottom toolbar.
  2. Every sheet must have a Selection Id filter to constrain it to the data the user has chosen with their shelf selection in Insight. Drag Selection Id from the insight_selection table in the Tables list to the Filter panel.
  3. To ensure the sheet is working with your selected scenario data during development, set the Selection Id filter to the id value displayed by the Insight view in Step 9. You can set the filter value either by picking the value from the list of possible values for the filter or by entering it as a custom value.

  4. To add a bar chart of Input value by interval across all scenarios, drag Array Indices and Scenario Path to the Columns shelf and ensure that they are configured as discrete dimensions (click on the pills to view the configuration). Drag Input Array to the Rows shelf and ensure that it is configured as an attribute. Drag Scenario Name to the Marks panel.

  5. Adding the sheet to a dashboard gives the developer control over the layout of the visualization. At the bottom of the workbook, click on the New Dashboard icon.
  6. Drag Sheet 1 onto the dashboard.
  7. On the Dashboard tab of the left pane, set Size to Automatic to make the chart full width. On the Layout tab, remove the title.
  8. Right-click on the area below the x axis and turn off the axis headers. Your dashboard should appear as shown below:

  9. Click File > Save As and save your Tableau workbook into the tableau directory of the Insight app project as myworkbook.twb. If the directory does not exist, it must first be created.
Completing the View
  1. The Tableau VDL component is not yet configured with the workbook and view that it is intended to embed. Open the project and VDL view in Xpress Workbench. In the View Designer Artboard select the Tableau component in the view. On the Attributes panel, set the workbook attribute to myworkbook and the view attribute to the name of your dashboard, Dashboard 1 by default.
  2. The default height of the components is 200px. Set the height attribute to 600px so that the bar chart occupies more of the view, see Embedding Tableau Views with the vdl-tableau Component
  3. Publish the app with the Tableau Workbook.
  4. Open the view in Insight to verify that it is displaying correctly.

Parent Topic Integrating Tableau Visualizations in Custom Views

© 2001-2025 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.