diff --git a/_includes/docs_menu.html b/_includes/docs_menu.html index d021aef0..74f8c94e 100644 --- a/_includes/docs_menu.html +++ b/_includes/docs_menu.html @@ -29,6 +29,9 @@ Remote Debugging of JavaScript and HTML
  • + Use Log Files to Troubleshoot Dashboard Extensions +
    • +
  • Hosting and Contributing to the Community Portal
    • diff --git a/assets/log_viewer.png b/assets/log_viewer.png new file mode 100644 index 00000000..0f65768f Binary files /dev/null and b/assets/log_viewer.png differ diff --git a/docs/trex_debugging.md b/docs/trex_debugging.md index a835af13..3551b879 100644 --- a/docs/trex_debugging.md +++ b/docs/trex_debugging.md @@ -41,7 +41,7 @@ If you are using Tableau Desktop on macOS, you need to open a Terminal window an ## Download the Chromium Browser In order to actually do any debugging, you'll need to use a Chromium-based browser. You can use a normal install of Chrome, but because of some version incompatibilities in the debugging protocol, we recommend using build 47.0.2526.0 of Chromium, which matches the version of the browser running inside Tableau (just download and unzip the file). -* [Chromium for Windows (47.0.2526.0)](https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Win%2F352221%2Fchrome-win32.zip?generation=1443839123039000&alt=media) | +* [Chromium for Windows (47.0.2526.0)](https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Win%2F352221%2Fchrome-win32.zip?generation=1443839123039000&alt=media) * [Chromium for macOS (47.0.2526.0)](https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Mac%2F352221%2Fchrome-mac.zip?generation=1443838516381000&alt=media) diff --git a/docs/trex_logging.md b/docs/trex_logging.md new file mode 100644 index 00000000..116cace5 --- /dev/null +++ b/docs/trex_logging.md @@ -0,0 +1,187 @@ +--- +title: Use Log files to Troubleshoot Dashboard Extensions +layout: docs +--- + +You can use the Tableau Desktop and Tableau Server log files to troubleshoot issues with your dashboard extension. The log files can help you identify and fix registration errors, and can help you track extension activity. You can use any text viewer, or tools like the Tableau Log Viewer, to filter the log files, so you can focus in on the activities of concern. + +Support for extensions is built-in to Tableau, so there is nothing you need to set up and no code you need to add to view extension activity in Tableau log files. + + +--- +**In this section** + +* TOC +{:toc} + +## Locate the Tableau log files + +By default, the Tableau Desktop log file (`log.txt`) is are stored in the following location: + +``` +Users//Documents/My Tableau Repository + +``` +The `log.txt` file contains information about dashboard extension registration and information about extension command execution. + +## Download and install the Tableau Log Viewer + +The Tableau Log Viewer is an open source tool that makes it easier to read Tableau log files. You can install the Log Viewer by downloading a `.zip` file for either Windows or MacOS. If you want to build the Tableau Log Viewer yourself, you can also download or clone the Log Viewer repository. + + +1. Download the latest release in the [Releases Section](https://github.com/tableau/tableau-log-viewer/releases){:target="_blank"} of the [Tableau Log Viewer](https://github.com/tableau/tableau-log-viewer){:target="_blank"} repository on GitHub. + +2. Extract `.zip` file on your local computer. Launch the Log Viewer application (`Log Viewer.exe` on Windows, or `Log Viewer.app` on MacOS). +3. Open the log file from the File menu, or drag and drop the Tableau log file into the Log Viewer window. + +The Tableau Log Viewer supports both Tableau Desktop and (most) Tableau Server log files. For more information, see the wiki pages on GitHub for [Tableau Log Viewer](https://github.com/tableau/tableau-log-viewer){:target="_blank"}. + + +## Find dashboard extension events +The Desktop Tableau log file (`log.txt`) is a JSON formatted file. The extensions activity is tagged with the key-value pair `"k":"extension"`. You can search the log for `extension`. For example, this entry shows successful registration. + +```json +{"ts":"2017-11-27T17:55:55.665", + pid":12100,"tid":"3d08","sev":"info","req":"-", + "sess":"-", + "site":"{FA6345B5-D64A-4ADB-9435-12F170D9B2AB}", + "user":"-", + "k":"extension", + "v":{"Event":"Extension Successfully Registered", + "id":"com.tableau.extensions.samples.datasources", + "name":"DataSources Sample"} +} +``` + +Although, you can use any file viewer or text editor, the Tableau Log Viewer makes finding the events easy to view and navigate. + +![]({{site.baseurl}}/assets/log_viewer.png) + + +---- + +## Troubleshooting errors that occur during registration +The extension registration process occurs during Tableau start up. This is when Tableau looks in the `Extensions` folder for the manifest files (`.trex`) files, and then parses the files to check for schema violations, or to check that there are duplicate identifiers. If the manifest file checks out, Tableau writes the event to the log file and the extension appears in the list of available extension in the dashboard. +There are two situations that can occur during the extension registration process that might cause errors. + +- Duplicate extension ids +- XSD Validation errors + + +### Duplicate extension identifers +Each dashboard extension must have a unique identifier. The identifier is specified in the manifest file. + +```xml + +``` + +Tableau uses the extension identifier and the extension version number to register the dashboard extension. At startup, Tableau checks that there are no duplicate identifiers. If an extension is found that has the same identifier as one that is already registered, an error is logged and the extension with the duplicate identifier is not registered and does not appear in the list of available extensions. + + + +``` +Error: Registration Failed: Multiple Extensions With ID, com.tableau.extensions.samples.settings, Found +file: Settings.trex +id: com.tableau.extensions.samples.settings +``` + + +### XSD Validation errors +The extensions manifest file (`.trex`) is an XML-based file. As part of the registration process, the `.trex` file validated against the XML schema definition file (XSD). If there are schema violations with the `.trex` file, the extension cannot be registered and XSD errors are written to the Tableau log file. The first error specifies the type of error and the name of the manifest file. + +```xml +Error: Registration Failed: XSD Validation Failed +file: Sample.trex + +``` + +Each XSD validation error in the file is logged separately, which makes it easier to locate and fix problems. For example, the following error shows the exact line number and location where the error occurred. In this case, the value for `extension-version` number was left blank `""`. + +``` +Error: Error(2,86): value '' does not match regular expression facet '[0-9]\.[0-9]' (id: C:\Users\me\Documents\My Tableau Repository (Beta)\Extensions\Sample.trex) +file: Sample.trex +``` + + +---- + + +## Track extension activity + +In addition to troubleshooting errors during registration, you can track extension activity. There are other types of events that are reported with the `extension` keyword, such as successful registration, and command execution. The following section walks through the events that occur when the extension is successfully registered, and then placed on the dashboard. + +### Successful registration + +When no errors are found with the manifest file, Tableau completes the registration process and writes `Extension Successfully Registered` to the log file. At this point, the extension is available for use. + +``` +Event: Extension Successfully Registered +id: com.tableau.extensions.dashboard.tutorial.final +name: Tutorial - Complete + +``` + +You can use the `id` of the extension, in this case `com.tableau.extensions.dashboard.tutorial.final` to search for instances where the extension is used. + +### Drop-on-dashboard + +When you drag an extension on to the dashboard a series of events take place. Using the id of the extension, you can find the sequence of `command-pre` and `command-post` tabdoc events that place the extension in the dashboard. + +``` +args: tabdoc:drop-on-dashboard add-as-floating="false" dashboard="Overview" drop-location={"x": 36,"y": 259} is-horizontal="false" zone-param="com.tableau.extensions.dashboard.tutorial.final" zone-type="add-in" +name: tabdoc:drop-on-dashboard +``` + +### Extension initialization + +After an extension has been placed in a dashboard, an initialization sequence begins. + +``` +Event: Executing Command: initialize-add-in-instance +id: com.tableau.extensions.dashboard.tutorial.final +instance-id: com.tableau.extensions.dashboard.tutorial.final +name: Tutorial - Complete + +``` +A key part of this is that the extension is assigned an `add-in-instance-id`. This instance id is something you can use to further track activity. + +``` +args: tabdoc:initialize-add-in-instance add-in-locator-pres-model={"add-in-instance-id": "36C4012514F042DB8F2AB466B445726A","sheet-path":{"sheet-name": "Overview","is-dashboard": true}} +name: tabdoc:initialize-add-in-instance +``` + + +### Executing Save-Settings + +In this example, the extension we are following calls `tableau.extensions.settings.saveAsync()` function when a selection has been made. + +``` +Event: Executing Command: save-add-in-settings +id: com.tableau.extensions.dashboard.tutorial.final +instance-id: com.tableau.extensions.dashboard.tutorial.final +name: Tutorial - Complete +``` +In this case, the selection was the name of a worksheet ("Sale Map"). + +``` + args: tabdoc:save-add-in-settings add-in-locator-pres-model={"add-in-instance-id": "36C4012514F042DB8F2AB466B445726A","sheet-path":{"sheet-name": "Overview","is-dashboard": true}} add-in-settings={"sheet":"Sale Map"} +name: tabdoc:save-add-in-settings +``` + +You can use the information in the log file to help you track activity, and to help you troubleshoot problems with extension registration. + +----- + +## List of extension events + +| Error | Description | +| --- | --- | +| Duplication error | Manifests with the same id. The id and file name are logged. +| XSD Validation error | Details of the errors are logged in separate messages. The file name is logged + + +| Info | Description | +| --- | --- | +| Registration success | The id and name of the extension. +| Command Execution | Logs when and what command the extension is executing. The Id, instance-Id, and extension name are logged as well. + diff --git a/docs/trex_manifest.md b/docs/trex_manifest.md index 290e62ad..f0cb99f0 100644 --- a/docs/trex_manifest.md +++ b/docs/trex_manifest.md @@ -3,10 +3,10 @@ title: Tableau Extension Manifest File layout: docs --- -The extension manifest file (`.trex`) contains metadata for the add-in and is used for registration. +The extension manifest file (`.trex`) contains metadata for the extension and is used for registration. For details about a manifest or its fields, see the [Sample Manifest File](#sample-manifest-file) and [Elements of the Manifest File](#elements-of-the-manifest-file). -For documentation about creating a manifest file, see [Create a Tableau Add-In]({{site.baseurl}}/docs/trex_getstarted#create-a-manifest-file). + **In this section** @@ -16,13 +16,13 @@ For documentation about creating a manifest file, see [Create a Tableau Add-In]( ## XSD Validation -The manifest is an XML-based file. We have provided an XSD that can be used to validate the user defined XML. The XSD is available from the [Extensions API Developer Preview](https://prerelease.tableau.com/project/version/item.html?cap=52e2710a0793434d82142736c7ab3029&arttypeid={0DD668AE-472C-4E70-B465-35F7AE0DEB6D}&artid={939493D2-8000-4192-857A-67624CBCC35A}) site. It is highly recommended that you validate the manifest XML before use. +The manifest is an XML-based file. We have provided an XSD (an XML schema definition file) that can be used to validate the manifest file you have created for your extension. The XSD is available from the [Extensions API Developer Preview](https://prerelease.tableau.com/project/version/item.html?cap=52e2710a0793434d82142736c7ab3029&arttypeid={0DD668AE-472C-4E70-B465-35F7AE0DEB6D}&artid={939493D2-8000-4192-857A-67624CBCC35A}) site. You are strongly encouraged to validate your extensions manifest file before using it for the first time. ## Manifest Versioning The versioning of the manifest is designed to be semantically simple and support compatibility. The version follows the [Major].[Minor] format. Minor upgrades are backwards compatible while major upgrades involve breaking changes. ## Error Reporting -At start up, Tableau checks the manifest file. If any XML errors are found while parsing the file, Tableau writes these errors to the `log.txt` file in the `My Tableau Repository (Beta)/Logs` folder. This is the same location that Tableau Desktop uses to report other errors and activity. +At start up, Tableau checks the manifest file. If any errors are found while parsing the file, Tableau writes these errors to the `log.txt` file in the `My Tableau Repository (Beta)/Logs` folder. This is the same location that Tableau Desktop uses to report other errors and activity. If a workbook is saved with an extension and then later opened on another computer that does not have the extension installed, Tableau displays a message in the dashboard zone where the extension would have appeared that states the extension is not available. @@ -31,21 +31,18 @@ If a workbook is saved with an extension and then later opened on another comput ```xml - - + + en_US - Addin Description - - - + Extension Description 1.1 - SERVER:PORT + SERVER:PORT/PATH Base64-Encoded ICON - + name in English @@ -75,45 +72,42 @@ If a workbook is saved with an extension and then later opened on another comput manifest The root element that contains the manifest options. - + manifest-version -The version of the manifest. Currently supported version is 0.1. +The version of the manifest. The version currently supported is 0.1. -tableau-addin -The root element that contains the options for the add-in. The tableau-addin includes the id attribute, which follows the reverse domain name pattern (com.tableau.addin), and add-in version number attribute. These attributes are required. +dashboard-extension +The root element that contains the options for the extension. The dashboard-extension includes the id attribute, which follows the reverse domain name pattern (com.example.extension), and extension-version number attribute. These attributes are required. -addin-version -The user defined version of the add-in. i.e. MyAddIn-1.0 +extension-version +The version of the extension. For example, extension-version="0.1.0" default-locale -Specifies the default local to use for localized text. Here both the locale format (en_US) and language code (en) are accepted. The locales here gets converted to one of the supported languages in Desktop UI. If the language is unsupported or invalid, English is set as default +Specifies the default locale to use for localized text. Here both the locale format (en_US) and language code (en) are accepted. The default locale specified here is converted to one of the supported languages in the Tableau UI. If the language is unsupported or invalid, English is set as default. name -The name of the add-in as it appears in the under Extensions on a dashboard sheet. To provide localized text, specify the name of the resource-id and provide the text strings in the resources element of the manifest (see the manifest example). You can provide localized strings for name and description. +The name of the extension as it appears under Extensions on a dashboard sheet. To provide localized text, specify the name of the resource-id and provide the text strings in the resources element of the manifest (see the manifest example). You can provide localized strings for name and description. description -A short description of the add-in. +A short description of the extension. -addin-type -Specifies the type of add-in. Currently, the only type supported is dashboard-addin. - - author -Specifies metadata about the author of the add-in, including name, email address, organization, and website. The name attribute is required. +Specifies metadata about the author of the extension, including name, email address, organization, and website. The name attribute is required. - + source-location Contains the url of the server that hosts the web page you create that interacts with Tableau. - + url -Specifies the name and port (optional) of the server, for example, <url>http://localhost:8080</url>. +Specifies the name and port (optional) of the server. The url must use HTTPS. For example: https://example.com/extension. +The exception is for localhost. In this case, HTTP is allowed. For example: http://localhost:8080. icon @@ -125,7 +119,13 @@ If a workbook is saved with an extension and then later opened on another comput min-api-version -Specifies the minimum API version required to run the Add In. This field is not yet used in this alpha version. Versioning support is still in progress +Specifies the minimum API version required to run the extension. This field is not used in this Developer Preview. Versioning support is still in progress. + +**Constraints** + +- String-based fields: 1000 characters +- URI-based fields: 2084 characters +- Icon field: size of images are restricted to 64x64 \ No newline at end of file diff --git a/docs/trex_release-notes.md b/docs/trex_release-notes.md index 08dbabae..eb89e0cd 100644 --- a/docs/trex_release-notes.md +++ b/docs/trex_release-notes.md @@ -10,9 +10,44 @@ layout: docs --- -### Developer Preview +### Developer Preview (0.7.0) +*November 29, 2017* -Initial release of the Tableau Extensions API. Provides supports for dashboard extensions. +- Update of the Tableau Extensions API. +- Tableau Extensions API library: `tableau-extensions-0.7.0.js` +- Tableau Desktop 10.5 RC, Tableau Server 10.5 (from [Extensions API Developer Preview](https://prerelease.tableau.com){:target="_blank"}) + +**Breaking change** + +- Schema change - Updated XSD file for the dashboard extensions manifest file (`.trex`). + If you have an existing extension, you must update the `.trex` file to follow the new schema. There is a script you can run that converts the manifest file for you. Or you can manually make the changes. For more information about the manifest, see [Tableau Extension Manifest File]({{ site.baseurl }}\docs\trex_manifest.html). You can download the manifest conversion script from the **Extensions API Developer Preview** on [https://prerelease.tableau.com](https://prerelease.tableau.com){:target="_blank"}. +- Existing workbooks - if you have an existing workbook that uses a dashboard extension, you will not be able to open it with this (`0.7.0`) release. To get around this issue, update the manifest file (`.trex`), update your extension to use `tableau-extensions-0.7.0.js`, and then open a new workbook and re-create the dashboard. + + +**New features** + +- Tableau Server. You can publish dashboards containing extensions and run them on Tableau Server. You can download a version of Tableau Server 10.5 that supports dashboard extensions from the **Extensions API Developer Preview** on [https://prerelease.tableau.com](https://prerelease.tableau.com){:target="_blank"}. +- Security - Your dashboard extension must use an HTTPS connection. If you are using `localhost` for development, you can still use HTTP. +- Sharing dashboards - the dashboard extension now gets saved with the workbook, so you can share your workbooks that use the extension with others. +- New method `DataSource.getConnectionSummariesAsync` gets a summary object for each underlying connection in a data source. +- New method `DataSource.getActiveTablesAsync` gets all tables used to create the data source (what you would see in the join canvas). + +- Logging - You can view dashboard extension activity in Tableau log files. Tableau records extension events that you can use to troubleshoot registration errors and command execution. See [Use Log files to Troubleshoot Dashboard Extensions]({{site.baseurl}}/docs/trex_logging.html). + + +**Bug fixes** + +- The `Worksheet.clearFiltersAsync` method no longer removes filters from your worksheets, but properly resets the filters to a default state. +- The name of the selected dashboard extension now appears instead of "other" in the dashboard Layout pane. + + + +--- + +### 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`