Doc updates for 0.7.0, logging, XSD changes

_includes/docs_menu.html

@@ -29,6 +29,9 @@
             <a href="{{ site.baseurl }}/docs/trex_debugging.html">Remote Debugging of JavaScript and HTML</a>
         </li>
         <li>
+            <a href="{{ site.baseurl }}/docs/trex_logging.html">Use Log Files to Troubleshoot Dashboard Extensions</a>
+        </li>
+		<li>
             <a href="{{ site.baseurl }}/docs/trex_contributing.html">Hosting and Contributing to the Community Portal</a>
         </li>
 

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) 
 
 

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/<username>/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
+<dashboard-extension id="com.tableau.extensions.samples.datasources" extension-version="0.7.0">
+```
+
+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. 
+

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
         <?xml version="1.0" encoding="utf-8"?> 
-        <manifest manifest-version="0.1" xmlns="http://wwww.tableau.com/xml/addin_manifest">
-          <tableau-addin id="com.tableau.addin" addin-version="0.1.0">
+        <manifest manifest-version="0.1" xmlns="http://wwww.tableau.com/xml/extension_manifest">
+          <dashboard-extension id="com.example.extensions.name" extension-version="0.1.0">
             <default-locale>en_US</default-locale>
             <name resource-id="name"/>
-            <description>Addin Description</description>
-            <addin-type>
-              <dashboard-addin/>
-            </addin-type>
+            <description>Extension Description</description>
             <author name="USERNAME" email="USER@example.com" organization="My Company" website="www.example.com"/>
             <min-api-version>1.1</min-api-version>
             <source-location>
-              <url>SERVER:PORT</url> 
+              <url>SERVER:PORT/PATH</url> 
             </source-location>
             <icon>Base64-Encoded ICON</icon>
-          </tableau-addin>
+          </dashboard-extension>
           <resources>
             <resource id="name">
               <text locale="en_US">name in English</text>
@@ -75,45 +72,42 @@ If a workbook is saved with an extension and then later opened on another comput
 <td><code>manifest</code></td>
 <td>The root element that contains the manifest options.</td>
 </tr>
-<tr class="event">
+<tr class="even">
 <td><code>manifest-version</code></td>
-<td>The version of the manifest. Currently supported version is 0.1. </td>
+<td>The version of the manifest. The version currently supported is 0.1. </td>
 </tr>
 <tr class="odd">
-<td><code>tableau-addin</code></td>
-<td>The root element that contains the options for the add-in. The <code>tableau-addin</code> includes the <code>id</code> attribute, which follows the reverse domain name pattern (<code>com.tableau.addin</code>), and add-in version number attribute. These attributes are required.</td>
+<td><code>dashboard-extension</code></td>
+<td>The root element that contains the options for the extension. The <code>dashboard-extension</code> includes the <code>id</code> attribute, which follows the reverse domain name pattern (<code>com.example.extension</code>), and <code>extension-version</code> number attribute. These attributes are required.</td>
 </tr>
 <tr class="even">
-<td><code>addin-version</code></td>
-<td>The user defined version of the add-in. i.e. MyAddIn-1.0</td>
+<td><code>extension-version</code></td>
+<td>The version of the extension. For example, <code>extension-version="0.1.0"</code></td>
 </tr>
 <tr class="odd">
 <td><code>default-locale</code></td>
-<td>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 </td>
+<td>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. </td>
 </tr>
 <tr class="even">
 <td><code>name</code></td>
-<td>The name of the add-in as it appears in the under <strong>Extensions</strong> 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.</td>
+<td>The name of the extension as it appears under <strong>Extensions</strong> 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.</td>
 </tr>
 <tr class="odd">
 <td><code>description</code></td>
-<td>A short description of the add-in.</td>
+<td>A short description of the extension.</td>
 </tr>
 <tr class="even">
-<td><code>addin-type</code></td>
-<td>Specifies the type of add-in. Currently, the only type supported is <code>dashboard-addin</code>.</td>
-</tr>
-<tr class="odd">
 <td><code>author</code></td>
-<td>Specifies metadata about the author of the add-in, including <code>name</code>, <code>email</code> address, <code>organization</code>, and <code>website</code>. The <code>name</code> attribute is required.</td>
+<td>Specifies metadata about the author of the extension, including <code>name</code>, <code>email</code> address, <code>organization</code>, and <code>website</code>. The <code>name</code> attribute is required.</td>
 </tr>
-<tr class="even">
+<tr class="odd">
 <td><code>source-location</code></td>
 <td>Contains the <code>url</code> of the server that hosts the web page you create that interacts with Tableau.</td>
 </tr>
-<tr class="odd">
+<tr class="even">
 <td><code>url</code></td>
-<td>Specifies the name and port (optional) of the server, for example, <code>&lt;url&gt;http://localhost:8080&lt;/url&gt;</code>.</td>
+<td>Specifies the name and port (optional) of the server. The <code>url</code> must use HTTPS. For example: <code>https://example.com/extension</code>. 
+The exception is for <code>localhost</code>. In this case, HTTP is allowed. For example: <code>http://localhost:8080</code>.</td>
 </tr>
 <tr class="even">
 <td><code>icon</code></td>
@@ -125,7 +119,13 @@ If a workbook is saved with an extension and then later opened on another comput
 </tr>
 <tr class="even">
 <td><code>min-api-version</code></td>
-<td>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</td>
+<td>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.</td>
 </tr>
 </tbody>
 </table>
+
+**Constraints** 
+
+- String-based fields: 1000 characters 
+- URI-based fields: 2084 characters
+- Icon field: size of images are restricted to 64x64