Extensions v1.11.0

In this release

• Added Environment.uniqueUserId.
• Added the SummaryDataChanged event type.
• Added the Worksheet.getVisualSpecificationAsync method.
• Fixed bug in getSelectedMarksAsync which would cause formattedValue to be incorrect in multi
  pane scenarios.
• Added experimental features as part of Viz Extensions Pre-Release.
• See other details in https://tableau.github.io/extensions-api/docs/trex_release-notes.html.

Extensions v1.10.0

In this release

• Updates to the input specification for createVizImageAsync. This release includes support for combination charts, charts with multiple mark types in the same visualization (requires Tableau 2022.4+).
• Adds support for a DataTableReader to support pagination (requires Tableau 2022.4+).
• Deprecated Worksheet.getSummaryDataAsync. Use Worksheet.getSummaryDataReaderAsync.
• UI.displayDialogAsync now supports different dialog styles (window, modal or modeless dialog boxes).
• Adds support for annotating marks with Worksheet.annotateMarkAsync, Worksheet.getAnnotationsAsync, and Worksheet.removeAnnotationAsync.
• Map file is now included for better debugging experience with minified library.
• See other details in https://tableau.github.io/extensions-api/docs/trex_release-notes.html.

DataTableReader Introduction

There has always been a 10k row limit on getUnderlyingTableDataAsync and on
getLogicalTableDataAsync, and for large worksheets, getSummaryDataAsync can prove to be
unreliable.

Introducting DataTableReader! Starting with Tableau 2022.4 and Extensions v1.10.0,
DataTableReader provides an API to request data a page at a time.

Fetching a DataTableReader

To get a DataTableReader use one of the new functions: getSummaryDataReaderAsync,
getUnderlyingTableDataReaderAsync, or getLogicalTableDataReaderAsync. The parameters to these
functions include the GetSummaryDataOptions or GetUnderlyingDataOptions, but also include a page
row count. This parameter sets the size of pages that will be returned. The default, and maximum,
page size is 10,000 rows.

Using a DataTableReader

Converting your code to use a DataTableReader is straightforward.

The following:

const dataTable = await this.worksheet.getSummaryDataAsync();
// ... use dataTable ...

becomes:

const dataTableReader = await this.worksheet.getSummaryDataReaderAsync();
const dataTable = await dataTableReader.getAllPagesAsync();
await dataTableReader.releaseAsync();
// ... use dataTable ...

Or alternatively:

const dataTableReader = await this.worksheet.getSummaryDataReaderAsync();
for (let currentPage = 0; currentPage < dataTableReader.pageCount; currentPage++) {
    const currentPageDataTable = await dataTableReader.getPageAsync(currentPage);
    // ... process currentPageDataTable ...
}
await dataTableReader.releaseAsync();

Limits on a DataTableReader

Unfortunately, we still live a a world with limited computing resources. A DataTableReader consumes
server resources. Therefore, there are still limits on the number of rows supported for underlying
and logical data table readers. The default limit is approximately 1 million rows of data for
getUnderlyingTableDataReaderAsync, and approximately 32 million cells (rows * columns) for
getLogicalTableDataReaderAsync. Server administrators (starting in 2023.1) may change these limits to better match
computing resources with the Tableau Server (Cloud) or Tableau Desktop options:

• ExtensionsAndEmbeddingReaderRowLimit for getUnderlyingTableDataReaderAsync or
• ExtensionsAndEmbeddingReaderCellLimit for getLogicalTableDataReaderAsync.

Hints on using a DataTableReader

• If you are dealing with large amounts of data, set the columns to include, or the
  IncludeDataValuesOption to what you need. Fetching all columns, or requesting formatted data
  when you don't need various column or formatted data take significantly more time and resources.
  The option IncludeDataValuesOption.OnlyNativeValues is your friend for very large underlying or logical
  table data.
• Only one DataTableReader per logical table id is supported.
• Call DataTableReader.releaseAsync() when you are done processing the data. You can always
  request another one if you need to do more processing after some period of inactivity or user
  action.

Extensions v1.9.0

Changes in the Dashboard Extensions API:

• Added the Filter.getAppliedWorksheets() and Filter.setAppliedWorksheets() methods.
• Added the Dashboard.getFiltersAsync() and Dashboard.applyFilterAsync() methods.
• Added the Worksheet.applyRelativeDateFilterAsync method.
• Support for Tableau and Benton Sans fonts. You can now load these fonts during initialization.

For more information, see the Release Notes for Tableau Dashboard Extensions API version 1.9.0.

Extensions v1.8.1

Changes in the Dashboard Extensions API:

• Bug fixes
• Documentation updates

For more information, see the Release Notes for Tableau Dashboard Extensions API version 1.8.1.

Extensions v1.8.0

Changes in the Dashboard Extensions API:

Added new enums available to createVizImageAsync:

• VizImageSortDirectionType
• VizImagePaletteType
• VizImageSizeSettingType
• VizImageSizeSettingAlignmentType

For more information, see the Release Notes for Tableau Dashboard Extensions API version 1.8.

Extensions v1.7.0

Changes in the Dashboard Extensions API:

• Added moveAndResizeDashboardObjectsAsync

• Added replayAnimationAsync

• Added support for using Tableau workbook formatting (CSS) in dashboard extensions

• Added DashboardLayoutChanged event type

• Added setClickThroughAsync and support for dashboard extension transparency

Some new features require Tableau 2021.4 and later. See the Release Notes for Tableau Dashboard Extensions API version 1.7.

Extensions v1.6.0

Extensions v1.6 introduces Tableau Viz, a new way to create visualizations that you can add to dashboard extensions.
For more information, see Add Tableau Viz to your Dashboard Extensions.

Changes in the Dashboard Extensions API:

• Added the getAllDataSourcesAsync() method to get the data sources for a workbook.
• Added the createVizImageAsync() method to support Tableau Viz.

See the Release Notes for Tableau Dashboard Extensions API version 1.6.

Please notice that the default branch is now main. If you use git to checkout extensions-api, please switch to the main branch with git checkout main.

Extensions v1.5.0

The theme of 1.5.0 is flexibility leading to improved performance. All of the added options and functions allow you as developers to request the data you need, and not spend time requesting data that you do not need. In the DataSourceUnderlyingDataOptions, and GetSummaryDataOptions, you can specify exactly what you want returned. This will reduce both the compute time and transfer size of the data. In addition, internally the payload for all the Get...DataAsync calls changed to reduce the size of the data. Please note that while all these options and functions work with previous versions of Tableau, to recognize the speed improvements, Tableau 2021.2 or newer will be needed.

All of the Get...DataAsync calls return a DataTable with rows of DataValue objects. Notice that DataValue provides both a nativeValue, and a formattedValue property.

export interface DataValue {
  /* tslint:disable:no-any */
  /**
   * @since 1.2.0 Fixes the type to be the raw native value rather than a string.
   * @returns  Contains the raw native value as a JavaScript type, which is
   *           one of string, number, boolean, or Date (as a string). Please note that special
   *           values, regardless of type, are always returned as a String surrounded by
   *           percent signs, such as '%null%', or '%no-access%'.
   */
  readonly value: any;
  /**
   * @since 1.4.0
   * @returns The raw native value as a JavaScript type, which is
   *          one of string, number, boolean, or Date object. Please note that special
   *          values are returned as null. The actual special value can be found
   *          in formattedValue, which would be something like 'Null', or 'No-Access'.
   *          Using nativeValue can greatly simplify your error checking since all values
   *          will be their native type value or null.
   */
  readonly nativeValue: any;
  /* tslint:enable:no-any */
  /**
   * @returns  The value formatted according to the locale and the
   *           formatting applied to the field or parameter.
   */
  readonly formattedValue?: string;
}

It turns out that many developers ignore one of these properties when processing results. The changes in 1.5.0 provide for requesting only the data that you need.

DataSourceUnderlyingDataOptions

DataSourceUnderlyingDataOptions has two new options: columnsToIncludeById, and includeDataValuesOption. Sometimes it is more convenient to work with field ids rather than names. The option columnsToIncludeById supports working with field ids. The option includeDataValuesOption supports requesting only native values or formatted values.

export interface DataSourceUnderlyingDataOptions {
  /**
   * Do not use aliases specified in the data source in Tableau. Default is false.
   */
  ignoreAliases?: boolean;
  /**
   * The columns to return specified by field name, returns all by default.
   */
  columnsToInclude?: Array<string>;
  /**
   * The columns to return specified by field id, returns all by default.
   * Since 1.5.0, fieldId is a property of the Column object.
   * @since 1.5.0
   */
  columnsToIncludeById?: Array<string>;
  /**
   * The maximum number of rows to return. 10,000 by default (this goes away once pagination is implemented)
   */
  maxRows?: number;
  /**
     * Specify which properties to return in DataValues. The default is 
     * `IncludeDataValuesOption.AllValues`.
     * This is a performance optimization only, and will be ignored in 
     * Tableau versions prior to 2021.2.
     *
     * @since 1.5.0
     */
  includeDataValuesOption?: IncludeDataValuesOption;
}

Here is an example call requesting only the native values. When OnlyNativeValues is requested, any DataValue.formattedValue will be undefined.

    let datasources = await this.worksheet.getDataSourcesAsync();
    let tables = await datasources[0].getLogicalTablesAsync();
    let dataTable = await datasources[0].getLogicalTableDataAsync(tables[0].id, {
      includeDataValuesOption: tableau.IncludeDataValuesOption.OnlyNativeValues,
    });

GetSummaryDataOptions & GetUnderlyingDataOptions

The property maxRows, was moved from GetUnderlyingDataOptions to GetSummaryDataOptions so that it is available to both. In addition, GetSummaryDataOptions now include the properties: columnsToIncludeById, and includeDataValuesOption. The option columnsToIncludeById can be used to request just a specified set of columns from either summary or underlying data. The option includeDataValuesOption supports requesting only native values or formatted values from summary or underlying data.

export interface GetSummaryDataOptions {
  /**
   * Do not use aliases specified in the data source in Tableau. Default is false.
   */
  ignoreAliases?: boolean;
  /**
   * Only return data for the currently selected marks. Default is false.
   */
  ignoreSelection?: boolean;
  /**
   * The columns to return specified by field id, returns all by default.
   * Since 1.5.0, fieldId is a property of the Column object.
   * @since 1.5.0
   */
  columnsToIncludeById?: Array<string>;
  /**
   * The number of rows of data that you want to return. A value of `0` will 
   * attempt to return all rows. `0` is the default if maxRows is not specified.
   * `getUnderlyingTableDataAsync' - maximum number of rows returned is 
   * capped at 10,000 regardless of maxRows.
   * `getSummaryDataAsync` - maximum number of rows returned is not capped, 
   * but performance may suffer for large row counts.
   *
   * @since 1.5.0 maxRows is now supported in both `GetSummaryDataOptions` 
   * and `GetUnderlyingDataOptions`.
   */
  maxRows?: number;
  /**
   * Specify which properties to return in DataValues. The default is 
   * `IncludeDataValuesOption.AllValues`.
   * This is a performance optimization only, and will be ignored in 
   * Tableau versions prior to 2021.2.
   *
   * @since 1.5.0
   */
  includeDataValuesOption?: IncludeDataValuesOption;
}

The following example shows requesting 10 rows, formatted data only, of one column of summary data.

    let dataTable = await this.worksheet.getSummaryDataAsync({
      maxRows: 10,
      includeDataValuesOption: tableau.IncludeDataValuesOption.OnlyNativeValues,
      columnsToIncludeById: [desiredFieldId],
    });

Column object

The Column object has an additional property fieldId. This fieldId can be used the columnsToIncludeById option.

export interface Column {
  /**
   * @returns  The name of the field in the column. In summary data, this includes 
   * the aggregation.
   * The summary data field name is not stable across languages.
   * For example, in an English version of Tableau, the field name might be 
   * SUM(Sales). In French, this would be SOMME(Sales).
   */
  readonly fieldName: string;
  /**
   * @since 1.5.0
   * @returns  The fieldId of the field in the column. In summary data, this 
   * includes the aggregation.
   * The fieldId is not stable across replacing data sources.
   * For example after replacing the data source 
   * [Clipboard_20210305T164000].[sum:Sales:qk] could become
   * [federated.12usuoq1171o1b1ebdyh60fjnev1].[sum:Sales:qk].
   */
  readonly fieldId: string;
  /**
   * @returns The data type of the column. Possible values are
   *           float, integer, string, boolean, date, and datetime.
   */
  readonly dataType: DataType;
  /**
   * @returns  Whether the column data is referenced in the visualization.
   */
  readonly isReferenced: boolean;
  /**
   * @returns  The number of rows in the returned data.
   */
  readonly index: number;
}

GetSummaryColumnsInfoAsync

There are times when you might be interested in column information, but not the data. Up until now, the only way to get the columns was to use getSummaryDataAsync. If the user has lots of data in their viz, this could be expensive. Use GetSummaryColumnsInfoAsync to quickly get the column information. Note that in Tableau versions prior to 2021.2, this will not be any faster than getSummaryDataAsync. To see a dramatic speedup, ensure the user is on version 2021.2+.

  /**
  * Gets the columns that are returned with `getSummaryDataAsync`.
  *
  * @returns The array of columns that describe the data in the worksheet.
  * @since 1.5.0
  */
  getSummaryColumnsInfoAsync(): Promise<Array<Column>>;

Other 1.5 improvements

• setZoneVisibilityAsync can now be used on any zone in the dashboard rather than just on floating zones.
• Filter.getFieldAsync has been fixed to properly return the field. This requires Tableau 2019.2+.

Release Extension 1.4.0

Dev (#323)

Release Extension 1.4.0

Extensions 1.3.0

• The Extensions API library version 1.3 (tableau.extensions.1.3.0.js) is backward compatible with previous releases of the library.

• Now available: Extensions API type definitions and new TypeScript samples. The latest release provides the TypeScript type definitions so that you can author your extension using TypeScript. See Use TypeScript with the Extensions API and TypeScript Sample Extensions{:target="_blank"} on GitHub.

• New all-values-selected property for categorical filters (filter.isAllSelected). You can use this new property to determine when all values of categorical filters are selected. The isAllSelected property is a Boolean and returns True or False. Prior to this release, there was no way to tell if all values of categorical filters were selected. The filter.appliedValues method returns empty array when (All) is selected, so there is no way to use that method to determine if all values are selected or if no values are selected. The isAllSelected property is available starting with Tableau 2019.2 and the Extensions API library version 1.3 (tableau.extensions.1.3.0.js).

  worksheet.getFiltersAsync().then((filters) => {
      let filter = filters[0];
      if (filter.filterType === tableau.filterType.Categorical)
      {
         console.log(filter.isAllSelected);
      }
  }