Release Notes for the Tableau Extensions API

Edit this page   Submit an issue

All Releases

Tableau Dashboard Extensions API version 1.10.0

December 2022

About this release:

See also: Known Issues

All Releases

Tableau Dashboard Extensions API version 1.9.0

June 2022

About this release:

Tableau Dashboard Extensions API version 1.8.1

February 2022

About this release:

Tableau Dashboard Extensions API version 1.8

November 2021

About this release:

This release contains updates for Tableau Viz, including:

For more information, see Tableau Viz Reference

Tableau Dashboard Extensions API version 1.7

October 2021

About this release:

Tableau Dashboard Extensions API version 1.6

September 2021

About this release:

Tableau Viz SVG image

Starting with version 1.6 of the Dashboard Extensions API library and Tableau 2021.3, you can now add Tableau visualizations to your dashboard extensions. Tableau Viz takes a declarative description of your visualization and renders it as an SVG image that you can embed in your extension. Version 1.6 of the Dashboard Extensions library adds the tableau.extensions.createVizImageAsync method, which takes a JavaScript object describing the image as an input.
For more information about using Tableau Viz, see:

New Dashboard Extension API methods in this release:

Tableau Dashboard Extensions API version 1.5

June 2021

About this release:

For more information about changes in this release, see Tableau Extensions v1.5.0.

Tableau 2021.1 Updates

March 2021

Tableau Dashboard Extensions API version 1.4

May 2020

About this release:

Bugs fixed in this release:

Tableau Sandboxed Extensions Development Environment

September 2019

Extensions API library v1.3

July 2019

About this release:

Extensions API library v1.2

April 2019

About this release:

Bugs fixed in this release:

Tableau 2019.1

February 2019

Changes in this release:

Bugs fixed in this release:

Tableau 2018.3

November 2018

New in this release:

TC18

October 2018

New in this release:

Bugs fixed in this release:

Tableau 2018.2

July 2018

Release of the Tableau Extensions API

Bugs fixed in this release:

Tableau 2018.2 (Beta 2)

June 4, 2018

Update of the Tableau Extensions API

Changes in this release:

  <manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
  ...      

  </manifest>   

<author name="tableau" email="github@tableau.com" organization="tableau" website="https://www.tableau.com"/>

Tableau 2018.2 (Beta 1)

April 26, 2018

Download Tableau Desktop, Tableau Server from Tableau 2018.2 Beta

Developer Preview (0.12.8)

April 13, 2018

Update of the Tableau Extensions API

Changes in this release:

Bugs fixed in this release:

Developer Preview (0.12.8)

April 13, 2018

Update of the Tableau Extensions API

Changes in this release:

Bugs fixed in this release:

Developer Preview (0.12.7)

March 28, 2018

Update of the Tableau Extensions API

Updated in this release:

Bug fixes:

Developer Preview (0.10.0)

February 28, 2018

Updates in this release:

For other changes with this release, see Known Issues on the Extensions API Developer Preview site.

Adding a configuration menu item

You can use a new callback function option to initializeAsync() as a way to create a configuration option that opens a window or dialog box for your extension. To do this you first add the context-menu option to the extensions manifest file (.trex).

Add <context-menu> to the .trex file

<!-- add to <dashboard-extension> section
  after <icon> and <permissions> -->

<context-menu>
    <configure-context-menu-item />
</context-menu>

Create a configuration function

When you initialize an extension, you can now pass an optional contextMenuCallbacks object to the initializeAsync() function. This object maps a special ID or key (which must be 'configure') to a function you create. The function you create, in conjunction with adding a <context-menu> item to the manifest, adds a new Configure… context menu item to the zone of the extension inside a dashboard. When the user clicks the context menu item, the configuration function you specified is executed.

For example, you could use the UI namespace and have the configuration function call the displayDialogAsync() function to create a dialog box that can be used to change settings for the extension. The parent (or initial window) for your extension, might have the following JavaScript code.


$(document).ready(function () {
    // ...
    // pass the object to initializeAsync() to map 'configure' key to a function called configure()
    // ...
    tableau.extensions.initializeAsync({'configure': configure}).then(function() {     
      // ...
	  // ... code to set up event handlers for changes to configuration 
      });
    });
  });



   function configure() { 
    // ... code to configure the extension
    // for example, set up and call displayDialogAsync() to create the configuration window 
	// and set initial settings and handle the return payload 
	// ...
    tableau.extensions.ui.displayDialogAsync(popupUrl, defaultIntervalInMin, { height: 500, width: 500 }).then((closePayload) => {
      // The promise is resolved when the dialog has been expectedly closed, meaning that
      // the popup extension has called tableau.extensions.ui.closeDialog.
      // ...

      // The close payload is returned from the popup extension via the closeDialog() method.
     // ....

    }).catch((error) => {
      //  ... 
      // ... code for error handling
      
    });
  }

To better understand how to use the context menu, and to see it in action, check out the updated UINamespace sample.

Developer Preview (0.9.0)

February 14, 2018

Updates in this release:

Updates to the UI namespace

This preview release introduces more options for the UI namespace. You can now control the initial sizing (height, width) of a modal dialog box (or popup). The modal dialog itself is an extension. Using the displayDialogAsync() and closeDialog() methods you can pass payloads between the calling extension and the extension running in the modal dialog box. For an example of how you can use the UI namespace to create a configuration dialog box, see the UINamespace sample. The sample also shows how to use the settings event to capture the new configuration. The sample source code has extensive comments that describe how to use these new features in the Extensions API.

Permissions added to access full data

To access the underlying data along with information about the data source, the extension must declare that it requires full data access in the extension manifest file (.trex).

An extension requires full data access, if the extension uses any of the following four APIs:

Worksheet.getUnderlyingDataAsync()

Datasource.getUnderlyingDataAsync()

Datasource.getActiveTablesAsync()

Datasource.getConnectionSummariesAsync()

If you use any of these APIs, you need to add a <permissions> element to the manifest file (.trex) and specify full data permission. The XML looks like the following:


<permissions>
    <permission>full data</permission>
</permissions>

The <permissions> element must be added under <dashboard-extension> in the manifest file. For a complete description of the manifest, see the Tableau Extensions Manifest File.

If full data is not declared in the manifest file, and the extensions calls one of the APIs that accesses any underlying data or data source information, the API call fails. In addition, an error is written to the Tableau log file (log.txt). If you are debugging the extension with the Chromium web browser, an error is reported the console pane. The error message would look similar to the following:

PermissionValidation.ts:26 Extension (name = DataSources Sample, ID = com.tableau.extensions.demo.local) is missing required permission: full-data
Error: internal-error: permission-denied: Missing required permission to run get-underlying-data(...)

Error codes for extensions

Errors that are returned from the Extensions API are custom Tableau Error objects that extends the standard JavaScript error object.

The Extensions API wraps the standard error object with an errorCode property. Any time you encounter an error when you are developing your extension, you can look at this errorCode to determine the cause. See Error Codes.

For an example of how to handle error conditions, see the UINamespace sample. The sample shows how you could handle the error condition that occurs if a user dismisses a modal dialog box (DialogClosedByUser). The following snippet illustrates this pattern:

tableau.extensions.ui.displayDialogAsync(args... ).then((args... ) => {
   //
   // code that sets up the extension in the modal dialog box
  // 
    }).catch((error) => {
      // One expected error condition is when the popup is closed by the user
      // (meaning the user clicks the 'X' in the top right of the dialog).  
      // This can be checked for with:
      switch(error.errorCode) {
        case tableau.ErrorCodes.DialogClosedByUser:
          console.log("Dialog was closed by user");
          break;
        default:
          console.error(error.message);
      }
    });

Developer Preview (0.8.0)

January 10, 2017

New desktop authoring experience

You no longer need to place the .trex file for the extension in a predetermined folder, you now do the following:

  1. In the dashboard, under Objects on the left, select Extension and drag it to the dashboard sheet on the right. The Select an Extension dialog box appears.
  2. The first time you open the dialog box to add an extension, you will see a link to Choose an Extension. Click the link and browse to the directory where you have the .trex file. Subsequently, when you drag the Extension on the dashboard, the dialog box shows you the most recently used list, choose from the list, or click Browse to select another extension.

New UI namespace

HTTPS and security

For information about the HTTPS requirements for extensions, see Security and Tableau Extensions

Remote Debugging

Due to changes in this release, remote debugging does not work as expected in Tableau Desktop. To enable debugging, you must add the --remote-debugging-port=8696 option to the command used to start Tableau. The easiest way to do this is to open the Tableau shortcut on the Start menu. Open the file location of the Tableau shortcut. Right-click the Tableau shortcut and click Properties. In the Target text box, append the remote debugging option to the command. Do not enclose the option in quotation marks.

   "C:\Program Files\Tableau\Tableau main\bin\tableau.exe" --remote-debugging-port=8696

For information about debugging extensions, see Remote Debugging of JavaScript and HTML.

Developer Preview (0.7.0)

November 29, 2017

Breaking change

New features

Bug fixes

Developer Preview (0.6.0)

Oct 10, 2017

Initial release of the Tableau Extensions API. Provides support for dashboard extensions.

Tableau Extensions API library: tableau-extensions-0.6.0.js

Tableau Desktop 10.5 beta