Documentation

//Documentation
Documentation 2018-07-03T15:05:03+00:00

What is a Tableau dashboard extension

Tableau dashboard extensions are web applications that have two-way communication with the dashboard. Dashboard extensions enable all sorts of scenarios, like letting you integrate Tableau with custom applications, making possible for you to modify the data for a viz, or even creating custom visualizations inside the dashboard. A dashboard extension is just one type of extension that can be built using the Tableau Extensions API.

You are more than welcome to participate in our forum discussions on Extensions and Solutions.

Components of a Tableau dashboard extension

A Tableau extension consists of a manifest file (.trex), a web page that uses a Tableau-provided JavaScript library, and the JavaScript file (or files) that contain your extension logic. The Tableau extensions are supported on Tableau Desktop.

Components of a Tableau Dashboard Extension

Extensions – Tableau Desktop Creator

Use a dashboard extension

You can use a dashboard extension like you would any other dashboard object. You can add extensions to your dashboard that provide new capabilities, or add extensions that integrate with other business applications directly in Tableau. You can create your own dashboard extension or use one that has been created by someone else. Extensions are web applications that can interact with the worksheets and data in Tableau. The dashboard extension must be hosted on a web server that is running locally on your computer, on a server in your domain, or on a third-party web server. (Click on the image for a larger view)

How to use Tableau Extensions in your dashboard

Where to find dashboard extensions

To add an extension, you need to have the dashboard extensions manifest file (*.trex). This is an XML file that specifies the properties and URL of the extension.

Our Free, Freemium and Premium extensions are available in different sizes. Check out our Extensions page for more detail. You can easily start with our Free Performance Insights extension for Tableau Dashboards.

For links and information about dashboard extensions you can download and use, see the test scenarios for Dashboard Extensions, which are available from the Tableau 2018.2 Beta release site.

For information about creating your own dashboard extensions, see the Tableau Extensions API documentation for developers on GitHub.

Add an extension to the dashboard

  1. Start Tableau and open a workbook that has a dashboard, or open a workbook and create a new dashboard.
  2. In the dashboard, under Objects, select Extensionand drag it on to the dashboard.
  3. In the Choose an Extension dialog box, click Choose.
    Every Tableau extension has a manifest file (.trex) that describes the extension and identifies the location of the web application.
  4. If prompted, allow or deny the dashboard extension access to the data in the workbook.
    All extensions have access to the summary data in the dashboard (this is the visible data). Some dashboard extensions might request access to full data, which includes the underlying data in the view, and information about the data sources, such as the names of the connection, fields, and tables. For more information, Data security and dashboard extensions.If access is granted, the dashboard extension appears and runs through the initialization sequence. Follow any on screen instructions for configuring and running the extension with your dashboard.

Configure a dashboard extension

Some dashboard extension provide a configuration option that allows you to select the settings to apply. If the extension provides configuration option, you can access the settings from the shortcut menu in the dashboard zone.

  1. Select the extension zone in the dashboard, and click More Options from the drop-down menu in the upper-right corner.
  2. Click Configure….Follow the on-screen instructions for configuring the extension.

Reload a dashboard extension

If the dashboard extension becomes unresponsive or in some unworkable state, you might need to reload it. Reloading the extension is similar to refreshing a web page in a browser.

  1. Select the extension zone in the dashboard, and click More Options from the drop-down menu in the upper-right corner
  2. Click Reload.
    The dashboard extension is refreshed and should be set to its original starting state. If reloading the extension fails to restore it to a useable state, you can try removing the extension and adding it to the dashboard again.

Remove a dashboard extension

You can remove a dashboard extension from the dashboard just like you can remove any other dashboard object.

  1. Select the extension zone in the dashboard, and click Remove from Dashboard from the drop-down menu in the upper-right corner.

Data security and dashboard extensions

Dashboard extensions are web applications, and like web page objects, they can be running on web servers that could be located outside of your local domain. Before adding an extension to the dashboard, or viewing a dashboard that has an extension, you want to be certain you trust the web sites that host them.

By default, dashboard extensions must be running over the HTTPS protocol, which guarantees an encrypted channel for sending and receiving data, and ensures some privacy and security.

Allowing the extension access

Unlike web page objects, dashboard extensions can have access to the summary data (visible data) in a view, or can have access to the underlying data and information about the data source (names of tables, columns) and information about the data source connection. When you add an extension, or view a dashboard that has an extension, you have the opportunity to allow or deny the extension to run.

If you are adding an extension and you decide to not allow the extension to run, you return to the Choose an extension dialog box.

If you are viewing a dashboard that contains an extension that requires full data access, but that access is not granted, a message appears in place of the extension. If you trust the extension and want to use it, you can reset the permission and allow the extension to run.

Resetting permissions

You can choose to allow the extension to run by clicking Reset Permissions from the More Options drop-down menu of the layout container. This opens up the Allow Extensions dialog box where you can change permissions for the extension and allow it to run.

You can also choose to deny the extension permission, by clicking Reset Permissions from the drop-down menu for the extension. This opens up the Allow Extensions dialog box where you can change permissions for the extension so that it is not allowed to run.

Enable JavaScript

Dashboard extensions interact with the data in the dashboard using the Tableau Extensions API library, a JavaScript library. If you want to use extensions, be sure to enable JavaScript in the dashboard security settings (Help > Settings and Performance > Set Dashboard Web View Security > Enable JavaScript).

How to use an extension on Tableau Server and Tableau Online

You can add extensions to dashboards on Tableau Desktop and publish the workbook and views to Tableau Server and Tableau Online. You can also use web authoring to add extensions to dashboards on Tableau Server and Tableau Online.

To enable extensions to run, the server administrator must enable extensions on the server and must add the extension to the safe list for the site. The server administrator can also set permissions for extensions that can access full data, and control when users are prompted to allow an extension to run. Check with the server administrator if you want to use a dashboard extension on Tableau Server. You and the server administrator should only allow those extensions that you have tested and trust because a dashboard extension has access to the summary data in the view, and could have or could require access to the underlying data and information about the data source.

Note: For Tableau Online only, the site administrator can add extensions to the safe list and can set the permissions for data access and can control the user prompts. The server administrator for Tableau Online can enable extensions on the server and can place extensions on a block list to prevent them from running.

For more information about using dashboard extensions on Tableau Server and Tableau Online, see Dashboard Extensions in Tableau Server.

Get support for dashboard extensions

Ofcourse we would love to share our knowladge and passion for extensions with you. Get in touch with us en let us know what you like or where you need some help.

To get help for a specific extension, use the dashboard extension support link. You can find this link by opening the About dialog box for the extension.

  1. Select the extension zone in the dashboard, click More Options from the drop-down menu in the upper-right corner, and click About.
  2. In the About dialog box, click Get Support.
    This link takes you to the support page of the developer or company who created the extension.

Tableau provides limited customer support for dashboard extensions. Tableau does not provide support for extensions or for other programs written to interface with the Extensions API. However, you can submit questions and ask for help on the Tableau developer community forums.

Tableau does provide support for the Extensions API library and SDK though. If you find an issue with the Extensions API library or any of the developer samples, submit an issue on GitHub.

Ofcourse you can allways get in touch with one of our Extensions specialists and developers

Extensions – Tableau Server

Dashboard Extensions in Tableau Server

Dashboard extensions are web applications that run in custom dashboard zones and can interact with the rest of the dashboard using the Tableau Extensions API. Dashboard extensions give users the ability to interact with data from other applications directly in Tableau.

Note: You must be a server administrator to enable dashboard extensions on the server, or to block specific extensions from running. You must be a server administrator (or site administrator on Tableau Online) to add extensions to the safe list and to control the type of data the extensions can access. The server administrator (or site administrator on Tableau Online) can also configure whether users on the site will see prompts when they add or view extensions in a dashboard.

For information about using dashboard extensions in Tableau, see above Dashboard Extensions.

Before you run extensions on Tableau Server

Dashboard extensions are web applications and could be running on any computer set up as a web server. This includes local computers, computers in your domain, and third-party web sites. Because extensions could be hosted on third-party sites and could have access to the data in the dashboard, you want to only allow the extensions you trust. See Test extensions for security.

For security, the default settings for dashboard extensions on Tableau Server and Tableau Online limit the dashboard extensions that are allowed to run.

  • By default, only extensions that use the HTTPS protocol are allowed, which guarantees an encrypted channel for sending and receiving data (the only exception is for http://localhost).
  • By default, when extensions are enabled on the server, only extensions that require summary data (the aggregated data) from the view are allowed.
  • If the extension requires full data (access to the underlying data) the extension will not be able to run on Tableau Server or Tableau Online unless you explicitly add the extension to the safe list and grant the extension access to full data.

Control dashboard extensions access to data

Server administrators can control a global setting to allow extensions for all sites on the server. Server administrators can also put extensions on a global block list to prevent them from running. By default, extensions are enabled on the server (with the constraints previously described). To change this setting for the server, go to Manage All Sites > Settings > Extensions. If the server just has a single site, the global controls appear on the settings page for the site.

Server administrators can control whether to enable extensions for the site and whether to enable the default behavior (or policy) for extensions. That is, the default policy is that only extensions that request summary data are allowed to run on the site, and that all users will see prompts asking for permission to run. To change these settings for the site go to Settings > Extensions.

Server administrators can add or remove extensions from the safe list for a site. When you add an extension to the safe list, you can control whether to allow the extension to have access to full data.

Identifying an extension

As a web application, an extension is associated with a URL. You use this URL to test and verify the extension. You also use the URL to add the extension to the safe list to allow full data access, or to the block list to prohibit any access.

If you have the extension manifest file (.trex), an XML file that defines properties for the extension, you can find the URL from the  element.



    https://www.example.com/myExtension.html


				

If you have added the extension to the dashboard, you can find the URL from the extension properties. From the More Options menu, click About.

The About dialog box lists the name of the extension, the author of the extension, the web site of the author, along with the URL of the extension.

Add extensions to the safe list and configure user prompts

To ensure that users can use extensions that are trusted, you can add them to the safe list for the site.

On the safe list, you can control whether to grant the extension full data access. You can also control whether users will see a prompt asking them to allow the extension access to data. If the extension does not require full data access, you don’t need to add it to the safe list. You might want to add an extension to the safe list just so that you can configure whether or not users see the prompts.

  1. Go to Settings > Extensions.
  2. Under Enable Specific Extensions, add the URL of the extension. See Identifying an extension.
  3. Choose to Allow or Deny the extension Full Data Access.Full data access is access to the underlying data in the view, not just the summary or aggregated data. Full data access also includes information about the data sources, such as the names of the connection, fields, and tables. In most cases, if you are adding an extension to the safe list you will also be allowing to have access to full data.
  4. Choose to Show or Hide the User Prompts.Users see the prompts by default when they are adding an extension to a dashboard, or when they are interacting with a view that has an extension.

Block specific extensions

The default global policy allows unknown extensions to run, provided that they only access summary data. Server administrators can keep specific extensions from running by adding them to the block list for the server. If an extension is on the global block list it overrides any settings for the extension on the safe list for a site.

  1. To add an extension to the blocked list for the server, go to Manage All Sites > Settings > Extensions. On single-site installations, the block list is on the site Extensions settings page.
  2. Under Block Specific Extensions, add the URL of the extension. See above “Identifying an extension”.

Test extensions for security

Dashboard extensions are web applications that interact with data in Tableau using the Extensions API. Dashboard extensions contain JavaScript and could be hosted on sites outside of your domain. Because of this and the potential vulnerabilities, such as cross-site scripting, you should test and vet dashboard extensions before users use them in dashboards on Tableau Desktop, and before you allow extensions on Tableau Server.

Examine the source files

Dashboard extensions are web applications and include various HTML, CSS, and JavaScript files, and an XML manifest file (*.trex) that defines the properties in the extension. In many cases, the code for a dashboard extension is publicly available on GitHub and can be examined there or downloaded. In the manifest file (*.trex), you can find the source location, or URL indicated where the extension is hosted, the name of the author, and the web site of the author or company to contact for support. The  element specifies in the URL, the  element, specifies the name of the organization and the web site to contact for support (website="SUPPORT_URL"). The web site is the Get Support link user see in the About dialog box for the extension.

Many dashboard extensions reference external JavaScript libraries, such as the jQuery library or API libraries for third parties. Validate that the URL for external libraries points to a trusted location for the library. For example, if the connector references the jQuery library, make sure that the library is on a site that is considered standard and safe.

All extensions are required to use HTTPS protocol (https://) for hosting their extensions. You should examine the source files for the extension to ensure that any reference to external libraries is also using HTTPS or is hosted on the same web site as the extension. The one exception to the requirement of HTTPS is if the extension is hosted on the same computer as Tableau (http://localhost).

To the extent possible, make sure you understand what the code is doing. In particular, try to understand how the code is constructing requests to external sites, and what information is being sent in the request. In particular, check if any user-supplied data is validated to prevent cross-site scripting.

Understand data access

The Tableau Extensions API provides methods that can access the names of the active tables and fields in the data source, the summary descriptions of the data source connections, and the underlying data in a dashboard. If an extension uses any of these methods in a view, the extension developer must declare that the extension requires full data permission in the manifest file (.trex). The declaration looks like the following.



   full data

Tableau uses this declaration to provide a prompt to users at run time that gives them the option of allowing this access or not. If the extension uses any one of these four methods, without declaring full-data permission in the manifest file, the extension will load but the method calls will fail.

For information about how an extension accesses data from the dashboard, and the JavaScript methods used, see Accessing Underlying Data in the Tableau Extensions API. To get a better understanding about what the extension can find out about the data, you can use the DataSourcessample dashboard extension (available from the Tableau Extensions API GitHub repository) to see what data is exposed when the getDataSourcesAsync() method is called.

Test the extension in an isolated environment

If possible, test the dashboard extension in an environment that is isolated from your production environment and from user computers. For example, add a dashboard extensions to a safe list on a test computer or virtual machine that’s running a version of Tableau Server that is not used for production.

Monitor traffic created by the dashboard extension

When you test a dashboard extension, use a tool like FiddlerCharles HTTP proxy, or Wireshark to examine the requests and responses that the extension makes. Make sure that you understand what content the extension is requesting. Examine the traffic to be sure that the extension is not reading data or code that is not directly related to the purpose of the extension.