diff --git a/_includes/footer.html b/_includes/footer.html index 4feceb18..341829ed 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -3,6 +3,7 @@

This site is open source. Suggestions and pull requests are welcome on our GitHub page.

-

(c) Copyright 2018 Tableau

+

Legal Privacy ©Copyright 2003– Tableau

+ Documentation last generated on: {{ site.time }}
diff --git a/assets/css/main.css b/assets/css/main.css index 05fd446e..1ce47619 100644 --- a/assets/css/main.css +++ b/assets/css/main.css @@ -274,3 +274,8 @@ html { .size-1of3 { width: 33.333%; } +/* Legal and Privacy Links */ +.aLegal { + word-spacing: 8px; + padding-right: 8px; +} diff --git a/docs/trex_data_access.md b/docs/trex_data_access.md index 3b6f17fe..6159f7ba 100644 --- a/docs/trex_data_access.md +++ b/docs/trex_data_access.md @@ -5,11 +5,11 @@ layout: docs -The Extensions API provides several methods that can access the underlying data in a dashboard. The underlying data can include information about the data sources, such as the names of the connection, fields, and tables. Collectively, this information is sometimes called *full data*. Because of the potentially sensitive nature of this data, dashboard authors and people who use extensions need to know if the extension can access their data, and based upon this knowledge they might want to restrict this access. +The Extensions API provides several methods that can access the underlying data in a dashboard. The underlying data can include information about the data sources, such as the names of the connection, fields, and tables. Collectively, this information is sometimes called *full data*. Because of the potentially sensitive nature of this data, dashboard authors and people who use extensions need to know if the extension can access their data, and based upon this knowledge they might want to restrict this access. -To help ensure transparency and to give the users of extensions control, if your extension uses any of these methods that can access full data, you need to configure your extension to require **full-data** permission. The following section describes how you need to set up the permissions for your extension to run. +To help ensure transparency and to give the users of extensions control, if your extension uses any of these methods that can access full data, you need to configure your extension to require **full-data** permission. The following section describes how you need to set up the permissions for your extension to run. ---- +--- @@ -19,11 +19,17 @@ To help ensure transparency and to give the users of extensions control, if your {:toc} ---- +--- + +Starting in Tableau 2020.2, Tableau introduced a data model that supports flexible table relationships. To support this new model, the Extensions API version 1.4 provides new APIs that support the data model. +Because the data model changes the way the underlying data can be stored, some of the existing APIs will no longer work. +For more information about the data model in Tableau, see [The Tableau Data Model](https://help.tableau.com/current/pro/desktop/en-us/datasource_datamodel.htm){:target="_blank"}{:ref="noopener"}. + + ## What happens when extensions access full data -As a developer, you can choose the features and capabilities to implement using the Extensions API. One of these is the ability of the extension to access the underlying data in the dashboard or workbook. The `Worksheet` and `Datasource` interfaces have methods called `getUnderlyingDataAsync()` that return (as a promise) data tables containing the underlying data of the workbook or data source. The `Datasource` interface has two additional methods, `getActiveTablesAsync()` and `getConnectionSummariesAsync()` that return the names of the active tables and fields in the data source, and the summary descriptions of the data source connections. +As a developer, you can choose the features and capabilities to implement using the Extensions API. One of these is the ability of the extension to access the underlying data in the dashboard or workbook. The `Worksheet` and `Datasource` interfaces have methods that return (as a promise) data tables containing the underlying data of the workbook or data source. The `Datasource` interface has additional methods, `getLogicalTablesAsync()`, `getActiveTablesAsync()` (Deprecated), and `getConnectionSummariesAsync()` that return the names of the active tables and fields in the data source, and the summary descriptions of the data source connections. There are many cases where you need access to this underlying data so that your extension can perform a useful function. The only requirement for access is that the users of your extension are aware of it. If the extension uses any of the four methods, they are considered privileged, in that they require access to underlying data and data source information. To use any one of them, you need to add a declaration to your extension's manifest file (`.trex`) that states the extension requires **full-data** permission. Tableau uses this declaration to provide a prompt to users at run time that gives them the option of allowing this access or not. @@ -33,15 +39,18 @@ If the extension uses any of the four methods, they are considered privileged, i #### Extensions API methods that access full data -If your extension uses any one of the following methods, without declaring **full-data** permission in the manifest file, the extension will load but the method call will fail. If you have debugging enabled, Tableau will report an error in the JavaScript console and the error is also written to the Tableau log file. - -`Worksheet.getUnderlyingDataAsync()` - -`Datasource.getUnderlyingDataAsync()` +If your extension uses any one of the following methods, without declaring **full-data** permission in the manifest file, the extension will load but the method call will fail. If you have debugging enabled, Tableau will report an error in the JavaScript console and the error is also written to the Tableau log file. -`Datasource.getActiveTablesAsync()` - -`Datasource.getConnectionSummariesAsync()` +| Method | Current Status | +|------------------------------------------|-------------------------------------| +|`Worksheet.getUnderlyingTablesAsync()` | | +|`Worksheet.getUnderlyingTableDataAsync()` | | +|`Worksheet.getUnderlyingDataAsync()` | Deprecated starting with the v1.4 library | +|`Datasource.getLogicalTables()` | | +|`Datasource.getLogicalTableData()` | | +|`Datasource.getUnderlyingDataAsync()` | Deprecated starting with the v1.4 library | +|`Datasource.getActiveTablesAsync()` | Deprecated starting with the v1.4 library | +|`Datasource.getConnectionSummariesAsync()`| | If you use any of these APIs, you need to add a `` element to the manifest file (`.trex`) and specify **full-data** permission. The declaration will allow the extension to pass validation. Depending upon the situation, for example, the first time a user adds the extension, Tableau will prompt the user to allow or deny the extension to run. @@ -88,9 +97,7 @@ When users add an extension that requires full-data access, Tableau displays a p The name of the extension and its URL come from the values you add to the manifest file for the extension. These are the values you add for `` and the `` element under ``. - ---- - +--- ## What happens when users open a workbook that uses an extension @@ -99,20 +106,18 @@ When users open a dashboard that has an extension that requires full-data access ![]({{site.baseurl}}/assets/Load_Extensions_Dialog.png){:height="50%" width="50%"} -The **Allow an Extension** dialog box provides users information about your extension. This information includes links to the your website, as specified by the `website` attribute in manifest file (in the `` element). Users can click on the link under **Created By** to find out more about your extension. - The dialog box also indicates whether or not the extension requires full-data access and provides the URL of the extension. +The **Allow an Extension** dialog box provides users information about your extension. This information includes links to your website, as specified by the `website` attribute in manifest file (in the `` element). Users can click on the link under **Created By** to find out more about your extension. + The dialog box also indicates whether or not the extension requires full-data access and provides the URL of the extension. If a user clicks **Cancel**, the workbook is opened, but the extension is not loaded. In the layout container where the extension would normally appear, the following message appears: ``` - Extension was denied the required permission to run. -Permissions approval can be reset through the contect menu. +Extension was denied the required permission to run. +Permissions approval can be reset through the context menu. ``` + Users can use choose to allow the extension to run by using the clicking **Reset Permissions** from the **More Options** drop-down menu of the layout container. This opens up the **Allow Extensions** dialog box where the user can change permissions for the extension. ![]({{site.baseurl}}/assets/reset_perms.png){:height="50%" width="50%"} - - - diff --git a/docs/trex_debugging.md b/docs/trex_debugging.md index 1379c0c2..bbc45fc9 100644 --- a/docs/trex_debugging.md +++ b/docs/trex_debugging.md @@ -42,7 +42,7 @@ Tableau Desktop version | Chromium version | Chrome version * [Chromium for macOS (`chrome-mac.zip`) (79.0.3945.0)](https://commondatastorage.googleapis.com/chromium-browser-snapshots/index.html?prefix=Mac/706915/) -
Note If you are using Tableau 2019.1 or later, you can debug extensions in Tableau Desktop using the certain versions of Chrome (versions prior to 80). Currently, you can't use Chrome version 80 (or later) for debugging your extension.
+
Note If you are using Tableau 2019.1 or later, you can debug extensions in Tableau Desktop using certain versions of Chrome (versions prior to 80). Currently, you can't use Chrome version 80 (or later) for debugging your extension.
--- diff --git a/docs/trex_getdata.md b/docs/trex_getdata.md index d8214a91..d208f319 100644 --- a/docs/trex_getdata.md +++ b/docs/trex_getdata.md @@ -4,7 +4,12 @@ layout: docs --- The Extensions API provides methods that you can use to access the data in a dashboard. -The data you can access includes the summary or aggregated data, that is, the data visible in the worksheet, and also to the underlying data or full data, which can include data from all fields and tables in the data source. If your extension needs to access the full data, there are security implications and your extension needs to declare its intent, so that users of your extension can choose to allow or deny the extension access. See [Accessing Underlying Data]({{ site.baseurl }}/docs/trex_data_access.html) for more information. +The data you can access includes the summary or aggregated data, that is, the data visible in the worksheet, and also to the underlying data (or full data), which can include data from all fields and tables in the data source. If your extension needs to access the full data, there are security implications and your extension needs to declare its intent, so that users of your extension can choose to allow or deny the extension access. See [Accessing Underlying Data]({{ site.baseurl }}/docs/trex_data_access.html) for more information. + +

Note Tableau 2020.2 introduced a new data model. To support that model, the Extensions API provides new methods and data structures starting with version 1.4 of the Extensions API library. In the new data model, a data source could have multiple logical tables, and logical tables can contain one or more physical tables. If you have an existing extension that uses one of the deprecated methods to get underlying data, the method call could fail if the data source contains more than one logical table. You should update your extensions to use these new methods. The new methods are backward compatible with previous versions of Tableau. + +For information about the data model, see The Tableau Data Model.

+
--- **In this section** @@ -12,19 +17,30 @@ The data you can access includes the summary or aggregated data, that is, the da * TOC {:toc} - +--- # Get data from a worksheet -The Extensions API provides several methods for accessing data from a dashboard. The method you use depends in part upon how you want to use the data. When you have the worksheet object, you can get the summary (aggregated) data or the full or underlying data directly from the worksheet, using these methods: +The Extensions API provides several methods for accessing data from a dashboard. The method you use depends in part upon how you want to use the data, and on the version of Tableau and the Extensions API library you are using. When you have the worksheet object, you can get the summary data (aggregated data) or the full data (underlying data) directly from the worksheet, using these methods: + +| Method | Tableau Version | Extensions API Library | Status | +|:------ | :---------------| :--------------------- | +| `Worksheet.getSummaryDataAsync()` | Tableau 2018.2 and later | version 1.1 and later | Current | +| `Worksheet.getUnderlyingDataAsync()` | Tableau 2018.2 to 2020.1 | version 1.1 to 1.3 | Deprecated | +| `Worksheet.getUnderlyingTablesAsync` | Tableau 2018.2 and later | version 1.4 and later | Current | +| `Worksheet.getUnderlyingTableDataAsync` | Tableau 2018.2 and later | version 1.4 and later | Current | -`Worksheet.getSummaryDataAsync()` +The data is returned in a `DataTable` object. The object contains the columns and data values, and information about the data, whether it is underlying or summary data, and in the case of underlying data, whether there is more data than can be returned. -`Worksheet.getUnderlyingDataAsync()` +Starting in Tableau 2020.2, with the introduction of the new data model and logical tables, you need to use the `Worksheet.getUnderlyingTablesAsync` method to first return the array of `LogicalTable` objects. The `LogicalTable` objects returned are determined by the measures in the worksheet. -The data is returned in a `DataTable` object. The object contains the columns and data values, and information about the data, whether it is underlying or summary data, and in the case of underlying data, whether there is more data than can be returned. +| Object/Property| Description | +| :------------ | :---------- | +| `LogicalTable` | Object that represents a logical table in a data source, or logical table used in a worksheet | +| `LogicalTable.caption` | The name of the logical table as it appears in Tableau. | +| `LogicalTable.id` | The identifier used to specify the logical table. Use this value to call `getUnderlyingTableDataAsync`. | -You can also get the data from the selected marks in the worksheet, or the marks that are currently highlighted in the worksheet. The following two functions return a `MarksCollection`, which is an array of `DataTable`objects. +You can also get the data from the selected marks in the worksheet, or the marks that are currently highlighted in the worksheet. The following two functions return a `MarksCollection`, which is an array of `DataTable` objects. `Worksheet.getSelectedMarksAsync()` @@ -39,7 +55,7 @@ The first step for accessing data of any kind is to get the worksheet object (or // After initialization, ask Tableau what sheets are available const worksheets = tableau.extensions.dashboardContent.dashboard.worksheets; - // Find a specific worksheet + // Find a specific worksheet var worksheet = worksheets.find(function (sheet) { return sheet.name === "Name of Worksheet I want"; }); @@ -51,11 +67,10 @@ The first step for accessing data of any kind is to get the worksheet object (or ``` -After you have a worksheet object, you can call one of the methods to access the data for that worksheet. For summary data, or the data from the selected or highlighted marks, the steps are straight forward. If you want access the underlying data (or full data), there are additional steps and considerations. See [Accessing Underlying Data]({{ site.baseurl }}/docs/trex_data_access.html) - +After you have a worksheet object, you can call one of the methods to access the data for that worksheet. For summary data, or the data from the selected or highlighted marks, the steps are straight forward. If you want access the underlying data (or full data), there are additional steps and considerations. See [Accessing Underlying Data]({{site.baseurl}}/docs/trex_data_access.html). -## Example: Getting summary data +## Get summary data from a worksheet ```javascript @@ -70,17 +85,67 @@ After you have a worksheet object, you can call one of the methods to access the ``` -## Example: Getting full data +## Get full data from a worksheet If your extension uses one of the functions that can access full data, you need to add an element to the manifest file (`.trex`) that declares that the extension requires `full data` permission. If the manifest file does not have this element, the extension can run, but the method to access full data will fail. See [Add permissions to access full data to manifest file]({{ site.baseurl }}/docs/trex_data_access.html#add-permissions-to-access-full-data-to-manifest-file). Note whoever uses your extension must have the appropriate download permissions (Download Full Data) so that extension can run. +Starting in Tableau 2020.2, and using version 1.4 of the Extensions API v1.4 library, the methods for accessing the underlying data changed. You can use these methods in all versions of Tableau (starting with 2018.2) if you use the v1.4 library or later. + +### Get full data using the v1.4 library (and later) + +Starting in Tableau 2020.2 and later, where the underlying data could include multiple logical tables, you first need to identify the logical table (or tables) you want data from. In previous versions of Tableau, logical tables did not exist. When you use the `getUnderlyingTablesAsync` in Tableau 2020.1 and earlier, the method returns a single table. You can use this single table identifier to call `getUnderlyingTablesAsync`. + +#### 1. Get the logical table(s) using getUnderlyingTablesAsync() + +The first step is to use the `Worksheet.getUnderlyingTablesAsync()` method to return the array of `LogicalTable` objects. The `LogicalTable` objects returned are determined by the measures in the worksheet. If a worksheet's data source contains multiple logical tables and the worksheet only uses measures from one logical table, the method will return one logical table. + +To get the underlying data for each logical table, you use the `LogicalTable.id` property of the table to call `Worksheet.getUnderlyingTableDataAsync()`. Note that when you use the `getUnderlyingTablesAsync()` in Tableau 2020.1 and earlier, the method will only return a single table, and that table uses `single-table-id-sentinel` as the `LogicalTable.id`. + +```javascript + +// Call to get the underlying logical tables used by the worksheet +worksheet.getUnderlyingTablesAsync().then(logicalTables => { + // Get the first logical table's id + // In Tableau <= 2020.1, the first table is the only table returned. + const logicalTableId = logicalTables[0].id; + + // Use the logicalTableId to then get worksheet's underlying data + // by calling worksheet.getUnderlyingTableDataAsync(logicalTableId) + +}); + + +``` + +#### 2. Get data from the logical table(s) using getUnderlyingTableDataAsync() + +The following example returns data for the first logical table that is used by a worksheet called *"Sale Map"*. ```javascript -// the following example uses the Superstore workbook and gets the underlying data // for a specific worksheet. -// The example writes the values for a single column (states names) to the console. + var worksheet = tableau.extensions.dashboardContent.dashboard.worksheets.find(w => w.name === "Sale Map"); + worksheet.getUnderlyingTablesAsync().then(logicalTables => { + worksheet.getUnderlyingTableDataAsync(logicalTables[0].id).then(dataTable => { + // process the dataTable... + }); + }); + +``` +--- + +### Deprecated: Get full data (library v1.3 and earlier) + +If you were using 1.3 version of the Extensions API library (or earlier), you had to use the `getUnderlyingDataAsync` method to get the underlying data from a worksheet in Tableau 2020.1 and earlier. This method has been deprecated, but it shown here for completeness. + +If you want your extension to work in all versions of Tableau, you should use the latest library (version 1.4 or later) and the `getUnderlyingTablesAsync` and `getUnderlyingTableDataAsync` methods. + + +```javascript + +// the following example uses the Superstore workbook and gets the underlying data // for a specific worksheet. +// The example writes the values for a single column (states names) to the console. tableau.extensions.dashboardContent.dashboard.worksheets.find(w => w.name === "Sale Map").getUnderlyingDataAsync().then(dataTable => { let field = dataTable.columns.find(column => column.fieldName === "State"); let list = []; @@ -96,18 +161,107 @@ tableau.extensions.dashboardContent.dashboard.worksheets.find(w => w.name === "S # Get data from a data source -You can also get the underlying data from the data sources for the worksheet. To do that, you must acquire the data sources for the worksheet with a call to the `getDataSourcesAsync()` method, which returns an array of the primary and all the secondary data sources of a worksheet. Once you have the data source object, you can access the underlying data and access information about the data source, such as the names of tables and fields and information about the connection. Just like worksheet method, `getUnderlyingDataAsync()`, the following methods for the data source also require that your extension specifies `full data` permissions in the `trex` file. See [Add permissions to access full data to manifest file]({{ site.baseurl }}/docs/trex_data_access.html#add-permissions-to-access-full-data-to-manifest-file). +You can also get the underlying data from the data sources for the worksheet. To do that, you must acquire the data sources for the worksheet with a call to the `getDataSourcesAsync()` method, which returns an array of the primary and all the secondary data sources of a worksheet. Once you have the data source object, you can access the underlying data and access information about the data source, such as the names of tables and fields and information about the connection. -`Datasource.getUnderlyingDataAsync()` +Just like worksheet methods that access full data, the following methods for the data source also require that your extension specifies `full data` permissions in the `trex` file. See [Add permissions to access full data to manifest file]({{ site.baseurl }}/docs/trex_data_access.html#add-permissions-to-access-full-data-to-manifest-file). -`Datasource.getActiveTablesAsync()` -`Datasource.getConnectionSummariesAsync()` +| Method | Tableau Version | Extensions API Library | Status | +|:------ | :---------------| :--------------------- | +| `Datasource.getConnectionSummariesAsync()`| Tableau 2018.2 and later | version 1.1 and later | Current | +| `Datasource.getDataSourcesAsync()` | Tableau 2018.2 and later | version 1.1 and later | Current | +| `Datasource.getActiveTablesAsync()` | Tableau 2018.2 to 2020.1 | version 1.1 to 1.3 | Deprecated | +| `Datasource.getUnderlyingDataAsync()` | Tableau 2018.2 to 2020.1 | version 1.1 to 1.3 | Deprecated | +| `Datasource.getLogicalTablesAsync()` | Tableau 2018.2 and later | version 1.4 and later | Current | +| `Datasource.getLogicalTableDataAsync()` | Tableau 2018.2 and later | version 1.4 and later | Current | -## Example: Getting full data from a data source -The following example shows how you might find a specific data source of a worksheet, using the `getDataSourcesAsync()` method. The example then chains the data source returned in the promise to a call to the `getUnderlyingDataAsync()` method to access the data table. +## Get the data sources from a worksheet + +To get the data sources a worksheet uses, you call the `getDataSourcesAsync()` method on the worksheet object. The following code snippet shows how you might select a specific data source of a worksheet. + +```javascript + +tableau.extensions.dashboardContent.dashboard.worksheets.find(w => w.name === "Sale Map").getDataSourcesAsync().then(datasources => { + let dataSource = datasources.find(datasource => datasource.name === "Sample - Superstore"); + // return dataSource for further processing +}); + + +``` + +## Get full data from a worksheet using the v1.4 library (and later) + +After you have the data source object, you can query the data source for the underlying data. Starting in Tableau 2020.2 and later, the underlying data could include multiple logical tables. Before accessing the data you need to identify the logical table (or tables) of the data source you want data from. In previous versions of Tableau (2020.1 and earlier), logical tables did not exist. When you use the `Datasource.getLogicalTablesAsync()` in Tableau 2020.1 and earlier, the method returns a single table. + +#### 1. Get the logical table(s) using getLogicalTablesAsync() + +The first step in getting the underlying data is to call the `Datasource.getLogicalTablesAsync` method to return the array of `LogicalTable` objects. + +To get the underlying data for each logical table, use the `LogicalTable.id` property of the table to call `Datasource.getLogicalTableDataAsync()`. Note that when you use the `getLogicalTablesAsync` in Tableau 2020.1 and earlier, the method will only return a single table, and that table uses `single-table-id-sentinel` as the `LogicalTable.id`. + +Example using a single table: + +```javascript + +// Call to get the logical tables used by the worksheet +dataSource.getLogicalTablesAsync().then(logicalTables => { + // Get the first logical table's id + // In Tableau <= 2020.1, the first table is the only table returned. + const logicalTableId = logicalTables[0].id; + + // Use the logicalTableId to then get worksheet's underlying data + // by calling worksheet.getUnderlyingTableDataAsync(logicalTableId) + +}); + + +``` + +Example that writes the names of all the logical tables in the data source to the console: + +```javascript + +// Call to get the logical tables used by the worksheet +dataSource.getLogicalTablesAsync().then(logicalTables => { + // Loop through each table in this data source + logicalTables.forEach( table => { + console.log(table.caption); + }); +}); + + +``` + +#### 2. Get data from the logical table(s) using getLogicalTableDataAsync() + +After you have identified the logical tables you want, use the `LogicalTable.id` property of the table to call `Datasource.getLogicalTableDataAsync()` +The following example returns the column names of the first logical table that is in the data source. + + +```javascript + + dataSource.getLogicalTablesAsync().then(logicalTables => { + // get the underlying data from the first logical table + dataSource.getLogicalTableDataAsync(logicalTables[0].id).then(dataTable => { + // get the names of the columns in the dataTable + let list = []; + for (let col of dataTable.columns) { + list.push(col.fieldName); + } + console.log(list); + }); + }); + +``` + + +## Deprecated: Get data from a data source using the v1.3 library (and earlier) + +If you were using 1.3 version of the Extensions API library (or earlier), you had to use the `getUnderlyingDataAsync` method to get the underlying data from a data source in Tableau 2020.1 and earlier. This method has been deprecated, but it shown here for completeness. + +If you want your extension to work in all versions of Tableau, you should use the latest library (version 1.4 or later) and the `Datasource.getLogicalTablesAsync()` and `Datasource.getLogicalTableDataAsync` methods. ```javascript @@ -118,26 +272,39 @@ tableau.extensions.dashboardContent.dashboard.worksheets.find(w => w.name === "S // process the dataTable... }); +``` +--- -``` +# Compatibility: methods for accessing underlying data +To support the data model that was introduced in Tableau 2020.2, where a data source can have logical tables, the Tableau Dashboard Extensions API provides new methods for getting data. The new methods are available starting with version 1.4 of the Extensions API library. The following table shows the compatibility between the methods and the different versions of the Extensions API library and Tableau. + +If you have an existing Dashboard Extension that accesses underlying data, and you want your extension to work with Tableau 2020.2 or later, you should upgrade to version 1.4 of the library + +| Methods | API Version | Tableau 2020.1 and earlier | Tableau 2020.2 (single logical table) | Tableau 2020.2 (multiple logical tables) | +| :-------- | :---------- | :---------- | :--------- | :-------- | +| `Datasource.getUnderlyingDataAsync` `Worksheet.getUnderlyingDataAsync` | v1.3 and earlier | Works as expected | Works, column order will be different | Fails with an exception: Not Supported (2) | +| `Datasource.getUnderlyingDataAsync` `Worksheet.getUnderlyingDataAsync` | v1.4 | Works as expected | Works, column order will be different | Fails with an exception: Not Supported (2) | +| `Datasource.getLogicalTablesAsync` `Datasource.getLogicalTableDataAsync` `Worksheet.getUnderlyingTablesAsync` `Worksheet.getUnderlyingTableDataAsync` | v1.4 and earlier | Works, maps to existing commands | Works, column order will be different | Works as expected | + +--- # When there is more data than can be returned -Some data sources can be very large and could contain thousands and thousands of rows. To minimize the impact of requests for data on Tableau performance, the `getUnderlyingDataAsync()` method is currently limited to returning 10,000 rows. If the method can't return the full number of rows in your data, the `DataTable` property `isTotalRowCountLimited` is set to TRUE. You can use this property to test whether there is more data than can be returned. Note that the limits do not apply to `getSummaryDataAsync()`. +Some data sources can be very large and could contain thousands and thousands of rows. To minimize the impact of requests for data on Tableau performance, the `getUnderlyingDataAsync()`, `Worksheet.getUnderlyingTableDataAsync()`, and `Datasource.getLogicalTableDataAsync` methods are currently limited to returning 10,000 rows. If the method can't return the full number of rows in your data, the `DataTable` property `isTotalRowCountLimited` is set to TRUE. You can use this property to test whether there is more data than can be returned. Note that the limits do not apply to `getSummaryDataAsync()`. -The following table illustrates what happens to calls to `getUnderlyingDataAsync()` for various sizes of data (shown as **Data Rows**). +The following table illustrates what happens to calls to `getUnderlyingDataAsync()`, `Worksheet.getUnderlyingTableDataAsync()`, and `Datasource.getLogicalTableDataAsync()` for various sizes of data (shown as **Data Rows**). * `maxRows` represents the rows requested as one of the `GetUnderlyingDataOptions`. When `maxRows = 0` the method will attempt to return all rows of data. * `totalRowCount` represents the number of rows returned in the `DataTable`. * `isTotalRowCountLimited` is the Boolean that indicates if there is more rows of data than can be returned. -**Rows of data returned from getUnderlyingDataAsync** +**Rows of data returned** | Data Rows | maxRows (input) | totalRowCount (output) | isTotalRowCountLimited | Comments | -|-----------|------------------------|------------------------|------------------------|---------------------------------------------------------| +|:----------|:-----------------------|:-----------------------|:-----------------------|---------------------------------------------------------| | 15,000 | 0 | 10,000 | TRUE |   | | 15,000 | any number > 10,000 | 10,000 | TRUE | Any number greater than 10,000 exceeds the return limit | | 15,000 | 10,000 | 10,000 | FALSE |   | @@ -150,19 +317,14 @@ The following table illustrates what happens to calls to `getUnderlyingDataAsync | 10,000 | 10,000 | 10,000 | FALSE |   | | 10,000 | 200 | 200 | FALSE |   | - - - - - - +--- # Handle full data access and permission errors -When an extension needs full data access and the user does not have full data permission on the workbook, Tableau currently allows the extension to run, but Tableau will call the promise failure function if the extension calls `getUnderlyingData()`. This is shown in the following example. +When an extension needs full data access and the user does not have full data permission on the workbook, Tableau currently allows the extension to run, but Tableau will call the promise failure function if the extension calls `getUnderlyingData()`, `Worksheet.getUnderlyingTableDataAsync()`, and `Datasource.getLogicalTableDataAsync()`. This is shown in the following example. ```Javascript -Worksheet.getUnderlyingDataAsync().then(function(success) { +Worksheet.getUnderlyingTableDataAsync(logicalTables[0].id).then(function(success) { // called on success }, function (err) { // called on any error, such as when the extension @@ -171,4 +333,4 @@ Worksheet.getUnderlyingDataAsync().then(function(success) { ``` -An error is also printed to the console. If you use the `getUnderlyingData()` method, be sure to add error handling for the promise in case of failure. +An error is also printed to the console. If you use any of these methods to get the full data, be sure to add error handling for the promise in case of failure. diff --git a/docs/trex_release-notes.md b/docs/trex_release-notes.md index da96802b..10348be8 100644 --- a/docs/trex_release-notes.md +++ b/docs/trex_release-notes.md @@ -11,7 +11,32 @@ layout: docs ---- See also: [Known Issues]({{site.baseurl}}/docs/trex_known_issues.html) ---- +---- + +### Tableau Dashboard Extensions API version 1.4 +*March 2020* + +* Tableau Dashboard Extensions API library: `tableau.extensions.1.4.0.js`
(download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api){:target="_blank"}).
+ +* To support the logical and physical tables introduced in Tableau 2020.2, the Tableau Dashboard Extensions API (version 1.4) provides new APIs and data structures. Use these new methods to get the underlying data from data sources and worksheets. The new methods replace `getUnderlyingDataAsync`. Starting in Tableau 2020.2, a data source could have multiple logical tables, and logical tables can contain one or more physical tables. If you have an existing extension that uses one of the deprecated methods to get underlying data, the method call could fail if the data source contains more than one logical table. You should update your extensions to use these new methods. The new methods are backward compatible with previous versions of Tableau. + + | Interface | Deprecated method (v1.3 and earlier) | New method (v1.4 and later) | + | :------------------| :-------------- |:-----------| + | `Datasource` | `datasource.getActiveTablesAsync` | `datasource.getLogicalTablesAsync` | + | `Datasource` | `datasource.getUnderlyingDataAsync` | `datasource.getLogicalTableDataAsync` | + | `Worksheet` | Not Applicable | `worksheet.getUnderlyingTablesAsync` | + | `Worksheet` | `worksheet.getUnderlyingDataAsync` | `worksheet.getUnderlyingTableDataAsync` | + + To support the data model, the API also includes the `LogicalTable` object that has two properties: `caption` and `id`. The `caption` is the name of the logical table as it appears in Tableau. + + For more information about getting underlying data from data sources and worksheets, see [Get Data from the Dashboard]({{site.baseurl}}/docs/trex_getdata.html). + + For information about the data model, see [The Tableau Data Model](https://help.tableau.com/current/pro/desktop/en-us/datasource_datamodel.htm){:target="_blank"}{:ref="noopener"}. + +* `DataValue` now has a `nativeValue` member. This member represents the raw native value as a JavaScript type, which is one of string, number, boolean, or Date object. Note that special values are returned as null. The `nativeValue` helps simplify error checking as all values will either be their native type value or null. The `nativeValue` exists for *ALL* `DataValue` objects, including those returned from parameters, filters, selections, and underlying or summary data. + +---- + ### Tableau Sandboxed Extensions Development Environment *September 2019* @@ -20,7 +45,7 @@ See also: [Known Issues]({{site.baseurl}}/docs/trex_known_issues.html) * The Extensions API SDK provides a local development environment that replicates the Tableau Hosting Cloud Service for Sandboxed Extensions. You can test your Sandboxed extensions locally with the same sandbox policies before submitting the extension to Tableau for publication. See [Create and Test Sandboxed Extensions]({{site.baseurl}}/docs/trex_sandbox_test.html) and [Publish Sandboxed Extensions]({{site.baseurl}}/docs/trex_sandbox_publish.html). ---- +---- ### Extensions API library v1.3 *July 2019* diff --git a/docs/trex_sandbox_test.md b/docs/trex_sandbox_test.md index 6d99acf9..85404c10 100644 --- a/docs/trex_sandbox_test.md +++ b/docs/trex_sandbox_test.md @@ -40,7 +40,7 @@ To port an existing extension, make sure all resources and libraries are local t * Resources should be placed in the same folder as your extension web page(s), or in a sub-folder of that directory. All references must be relative. -* Review the suggested guidelines that all extensions should follow to reduce XSS vulnerabilities, see [Cross-Site Scripting and Extension Security]({{site.baseure}}/docs/trex_xss_guidance.html). +* Review the suggested guidelines that all extensions should follow to reduce XSS vulnerabilities, see [Cross-Site Scripting and Extension Security]({{site.baseurl}}/docs/trex_xss_guidance.html). * Sandboxed Extensions cannot connect to sites outside of the sandbox and cannot transfer data. For example, a Sandboxed extension cannot transfer data to be processed by other applications. If you need to connect to outside services or resources, you can create a Network Enabled extension. Network Enabled extensions can't run in the local sandbox environment or in the Tableau Hosting Cloud Service for Sandboxed Extensions. diff --git a/docs/trex_typescript.md b/docs/trex_typescript.md index 2276117d..3cebab94 100644 --- a/docs/trex_typescript.md +++ b/docs/trex_typescript.md @@ -10,7 +10,6 @@ The Extensions API is a JavaScript library. If you author in TypeScript, Tableau * TOC {:toc} -
Note If you want to examine and use TypeScript versions of several of the sample extensions in the Samples folder, see Samples-Typescript (GitHub) and follow the instructions to Use the TypeScript Samples.
@@ -22,6 +21,8 @@ The Tableau Extension API type definitions are available as an npm @types packag npm install @tableau/extensions-api-types ``` +
Note The version of the types package must match the version of the Extensions API library you are using. You can specify the library version by appending the version number to the package name (@n.n.n). For example, npm install @tableau/extensions-api-types@1.3.1. If you don't specify a version number, npm will install the latest released package.
+ ## Import the type definitions Import the Extensions API type definitions into your TypeScript code. It is best to only import the modules and interfaces that you need in your code.