Skip to main content

Tableau Workspace Extension Manifest File

The .trex file is how Tableau knows your extension exists. A workspace extension uses the same root wrapper as dashboard and viz extensions: <manifest manifest-version="0.1">. Declare <workspace-extension> instead of <dashboard-extension> or <worksheet-extension>.

There is no <layout> and no <encoding>. Those belong to extensions that live inside a workbook.

Desktop opens the extension from <entry-points>. One <source-location> is shared by every entry point. Inside <on-click>, the target is <side-pane/>.

Sample manifest file​

This is hello-world-extension.trex. It declares the two entry points Desktop renders, and both open a side pane.

<?xml version="1.0" encoding="utf-8"?>
<manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
<workspace-extension id="com.tableau.examples.hello-world" extension-version="0.0.1">
<default-locale>en_US</default-locale>
<name resource-id="name"/>
<description>A minimal workspace extension for Desktop entry-point testing.</description>
<author name="Tableau" email="dev@tableau.com" organization="Tableau" website="https://www.tableau.com"/>
<min-api-version>1.1</min-api-version>
<source-location>
<url>https://<YOUR-DOMAIN.com>/hello-world-extension/index.html</url>
</source-location>
<entry-points>
<authoring-toolbar region="primary">
<label resource-id="name"/>
<icon>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#666666">
<path d="M3 4h2v6h4V4h2v16H9v-8H5v8H3V4zm10 0h2l2 11 2-7h2l2 7 2-11h2l-3 16h-2l-3-8-3 8h-2L13 4z"/>
</svg>
</icon>
<on-click><side-pane/></on-click>
</authoring-toolbar>
<authoring-menu>
<label resource-id="name"/>
<on-click><side-pane/></on-click>
</authoring-menu>
</entry-points>
</workspace-extension>
<resources>
<resource id="name"><text locale="en_US">Hello World</text></resource>
</resources>
</manifest>

Put the .trex in My Tableau Repository/Extensions/. It is not saved into the workbook.

A hosted <url> is https, or http://localhost while you develop. A bundled extension uses a path relative to the package content/ directory. The package lives under My Tableau Repository/Packages/<package-id>/, with the .trex in extensions/. The package id and the extension id are different. A .twbx can carry a Packages/ copy, and that copy is the one used for that workbook. A standalone .trex in Extensions/ does not travel in a .twb or .twbx.

note

An installed extension is identified by its id, extension-version, and source URL together. Adding the same combination replaces the installed copy. A different version or a different URL is a separate extension.

Elements of the manifest file​

Name of elementDescription
manifestThe root element that contains the manifest options.
manifest-versionThe version of the manifest. The version currently supported is 0.1.
workspace-extensionThe element that contains the workspace extension. Requires id (reverse domain name, for example com.example.extension) and extension-version. Do not include <layout> or <encoding>. Declare <entry-points> for the authoring toolbar button and the authoring menu item.
extension-versionThe version of the extension. For example, extension-version="0.0.1". Together with id and the source URL, this identifies the installed extension.
default-localeSpecifies the default locale for localized text. Both the locale format (en_US) and a language code (en) are accepted. An unsupported or invalid language falls back to English.
nameThe name of the extension. To localize it, set resource-id and put the strings in resources. Hello World uses this resource for the toolbar and menu labels.
descriptionA short description of the extension.
authorMetadata about the author: name, email, organization, and website. name and website are required. website must use HTTPS and is the Get Support link in the About dialog box.
source-locationContains the single url loaded for every entry point.
urlA hosted URL (https://example.com/extension, or http://localhost:8765/...), or, inside a package, a path relative to content/.
entry-pointsWraps the triggers the extension adds. Each child is one entry point with its own label and target. An extension can declare more than one. All of them load the same source-location.
authoring-toolbarA button on the authoring toolbar. Requires region: primary, insights, or overflow. Children: label, an optional tooltip, an inline SVG icon, and on-click. Opens a side pane.
authoring-menuAn item on the authoring menu. Children: label and on-click. Opens a side pane.
labelThe button or menu text. Use a literal string, or resource-id plus a resources entry, as Hello World does.
tooltipOptional tooltip on a toolbar entry point.
on-clickRequired inside every entry point. The child element is <side-pane/>.
side-paneOpens the extension in a side pane.
iconThe optional icon inside a toolbar entry point, icon is an inline SVG. As a direct child of workspace-extension, the icon image should be a 70×70 PNG, Base64 encoded. Hello World uses only the toolbar SVG.
permissionsOptional. The only value is full data. Declare it if the extension calls Worksheet.getUnderlyingDataAsync(), Datasource.getUnderlyingDataAsync(), Datasource.getActiveTablesAsync(), or Datasource.getConnectionSummariesAsync().
context-menuOptional. Registers a Configure... item. The only allowed child is <configure-context-menu-item />. Map it to a configure function in initializeAsync(). The authoring menu entry point is a separate element.
resourcesLocalized strings for name, description, and entry-point label text.
min-api-versionThe minimum API version required to run the extension. Hello World uses 1.1.

Constraints

  • String-based fields: 1000 characters
  • URI-based fields: 2084 characters