# Tableau Data Apps

> Tableau Cloud data apps only. Dashboard, viz, and workspace extension guides are out of scope.

Use this file for Data Apps. The Dashboard and Viz manifest pages are included only for packaging a data app. Do not apply other Dashboard, Viz, or Workspace extension instructions.

## (Cloud-only Beta) Data Apps

The data apps beta is available only on Tableau Cloud.
Build custom analytical applications on governed Tableau data and share them through Tableau. A data app combines a custom web interface with Tableau data access and hosting. Its front-end resources are embedded in a packaged workbook and served by Tableau.

Start with the overview to understand the concepts, then follow the getting started and creation guides.


---

## Administration and Security for Data Apps

The data apps beta is available only on Tableau Cloud.

Administration and security guidance is available on two pages:

- [Manage data apps](./trex_dataapp_manage.md) covers site preparation, access review, publishing, and ongoing administration.
- [Data app security](./trex_dataapp_security.md) covers data permissions, hosted code, external origins, and Tableau REST API access.

---

## Data App Details

The data apps beta is available only on Tableau Cloud.

A data app is a Dashboard or Viz Extension whose web resources are packaged with a Tableau workbook. The workbook places the interface and connects its data sources; the package supplies its manifests and front-end code. Tableau serves the bundled resources when a viewer opens the published workbook. Application code runs in the viewer's browser and queries Tableau at runtime.

The examples below describe a worksheet-based app named **Regional Sales**, using a published data source named **Sales** with a **Region** field. The same package model supports Dashboard Extensions, with the corresponding dashboard placement and manifest.

### Files and package structure

An unpacked app has this structure:

```text
Regional Sales/
├── Regional Sales.twb
└── Packages/
    └── com.example.regional-sales/
        ├── manifest.json
        ├── extensions/
        │   └── data-app.trex
        └── content/
            ├── index.html
            └── src/
                ├── app.js
                ├── styles.css
                └── tableau.extensions.1.latest.js
```

| Element | Responsibility |
| --- | --- |
| `.twb` workbook | Contains the worksheet or dashboard, the extension instance and its settings, and the data-source connections. |
| `manifest.json` | Identifies the package and its version, display name, and author. |
| `.trex` extension manifest | Declares the extension's identity, placement type, entry page, minimum API version, and permissions. |
| `content/` | Contains the HTML entry page and all bundled scripts, styles, images, fonts, and other assets. |
| Extensions API library | Initializes the extension's connection to Tableau and exposes supported runtime APIs. |

The published `.twbx` is a ZIP archive with the `.twb` and `Packages/` at its root. The enclosing `Regional Sales/` directory is not an extra archive level. Resource paths must resolve inside the package; files on a developer's machine do not become available to viewers unless bundled.

### Package identity

`Packages/com.example.regional-sales/manifest.json` contains the package's display metadata:

```json
{
  "id": "com.example.regional-sales",
  "version": "1.0.0",
  "name": "Regional Sales",
  "author": "Example Company"
}
```

In this single-extension example, the package directory, package ID, and extension ID use the same unique reverse-domain identifier. The package and extension versions are `1.0.0`. A new distributed version needs consistent updated metadata. These fields describe the supplied example format; additional capabilities depend on the supported beta package schema.

### Extension manifest and entry page

`extensions/data-app.trex` describes the worksheet integration:

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
  <worksheet-extension id="com.example.regional-sales" extension-version="1.0.0">
    <default-locale>en_US</default-locale>
    <name resource-id="name" />
    <description>Regions from a published Tableau data source.</description>
    <author name="Example Company" email="support@example.com"
            organization="Example Company" website="https://example.com" />
    <min-api-version>1.11</min-api-version>
    <source-location>
      <url>index.html</url>
    </source-location>
    <icon>iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=</icon>
    <permissions>
      <permission>full data</permission>
    </permissions>
    <encoding id="field">
      <display-name>Data</display-name>
      <role-spec>
        <role-type>discrete-dimension</role-type>
        <role-type>continuous-dimension</role-type>
        <role-type>discrete-measure</role-type>
        <role-type>continuous-measure</role-type>
      </role-spec>
      <fields max-count="50" />
      <encoding-icon token="level" />
    </encoding>
  </worksheet-extension>
  <resources>
    <resource id="name">
      <text locale="en_US">Regional Sales</text>
    </resource>
  </resources>
</manifest>
```

`index.html` resolves under the package's `content/` directory. The icon is a small Base64 placeholder. The `field` encoding defines a Data tile on the Marks card; `50` is this example's field count, not a platform limit. The `full data` declaration does not grant additional Tableau data permissions.

The supplied apps declare minimum API version `1.11`. This is an Extensions API version, not a Tableau product version or a guarantee that every data app API is available. The library and Tableau environment must support the methods the app uses.

For dashboard placement, the `.trex` uses the [Dashboard Extension manifest](../dashext/trex_manifest.md) and the workbook hosts the extension in a dashboard zone. The example above uses the [Viz Extension manifest](../vizext/trex_viz_manifest.md) and a worksheet pane.

### Workbook integration

A package directory alone does not place the app in a view. The `.twb` contains an extension instance, a referenced extension manifest, and the app's data-source connection. The following XML fragments show the relationships inside a worksheet workbook; they are parts of the workbook, not standalone `.twb` files.

#### Extension instance

The app's worksheet contains this pane under `worksheet/table/panes`:

```xml
<pane selection-relaxation-option="selection-relaxation-allow">
  <view><breakdown value="auto" /></view>
  <mark class="VizExtension" />
  <add-in add-in-id="com.example.regional-sales"
          extension-url="tableaulocalext:///com.example.regional-sales/content/index.html"
          extension-version="1.0.0"
          instance-id="A1B2C3D4E5F60718293A4B5C6D7E8F90">
    <instance-settings />
    <type-settings><worksheet /></type-settings>
  </add-in>
  <encodings>
    <custom column="[sqlproxy.sales].[none:Region:nk]"
            custom-type-name="field"
            encoding-id="{8A740CEB-6657-25B6-6557-242364572290}" />
  </encodings>
</pane>
```

The `tableaulocalext:///` URL addresses the package's entry page. `add-in-id` and `extension-version` match the extension manifest. Instance and encoding identifiers must be unique for the instances they identify. The custom encoding refers to both the manifest's `field` encoding and the worksheet's Region column instance.

Under `workbook/referenced-extensions`, the corresponding `referenced-extension` contains a copy of the extension manifest and a `referenced-views` element:

```xml
<referenced-views>
  <referenced-view instances="1" viewId="Regional Sales" />
</referenced-views>
```

In the workbook's manifest copy, the display name is resolved to `<name>Regional Sales</name>` and the source URL is the full `tableaulocalext:///com.example.regional-sales/content/index.html` URL. The worksheet's `name`, its `window` name under `workbook/windows`, and this `viewId` all identify **Regional Sales**.

#### Published data-source connection

The workbook's top-level `datasources` contains the published source. This example uses site content URL `sales-site`, published data-source content URL `Sales`, and a placeholder Tableau Cloud host:

```xml
<datasource caption="Sales" inline="true" name="sqlproxy.sales" version="18.1">
  <repository-location id="Sales" path="/t/sales-site/datasources" site="sales-site" />
  <connection channel="https" class="sqlproxy" dbname="Sales"
              directory="/dataserver" port="443"
              server="your-pod.online.tableau.com"
              server-ds-friendly-name="Sales" username="">
    <relation name="sqlproxy" table="[sqlproxy]" type="table" />
  </connection>
  <column aggregation="Count" caption="Region" datatype="string"
          name="[Region]" role="dimension" type="nominal" />
</datasource>
```

The source's content URL is its repository identity; it is distinct from the display caption and REST API LUID. Host, site, repository identity, and field definitions must match the actual published source. Workbook format version `18.1` follows the supplied beta example and must be supported by the target environment.

The app's worksheet also lists that source and its field dependencies under `worksheet/table/view`:

```xml
<datasources>
  <datasource caption="Sales" name="sqlproxy.sales" />
</datasources>
<datasource-dependencies datasource="sqlproxy.sales">
  <column aggregation="Count" caption="Region" datatype="string"
          name="[Region]" role="dimension" type="nominal" />
  <column-instance column="[Region]" derivation="None"
                   name="[none:Region:nk]" pivot="key" type="nominal" />
</datasource-dependencies>
```

`sqlproxy.sales` is the workbook-local connection key shared by the source definition, worksheet source, dependencies, and encoding reference. Each additional source needs its own consistent key and a connection on the app's worksheet. An empty `datasources` element leaves the app without a source to query.

### Front-end resources and runtime data

`content/index.html` loads bundled resources using paths relative to itself:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Regional Sales</title>
    <link rel="stylesheet" href="./src/styles.css" />
    <script src="./src/tableau.extensions.1.latest.js" defer></script>
    <script src="./src/app.js" defer></script>
  </head>
  <body>
    <main>
      <h1>Regional Sales</h1>
      <pre id="result" role="status">Connecting to Tableau…</pre>
    </main>
  </body>
</html>
```

`content/src/app.js` initializes Tableau, selects the connected source by name, and requests Region values at runtime:

```javascript
async function render() {
  const output = document.getElementById('result');
  try {
    await tableau.extensions.initializeAsync();
    const sources = await tableau.extensions.workbook.getAllDataSourcesAsync();
    const source = sources.find((item) => item.name === 'Sales');
    if (!source) throw new Error('The Sales data source is not connected.');

    const result = await source.queryAsync({
      fields: [{ fieldCaption: 'Region' }],
    });
    output.textContent = JSON.stringify(result, null, 2);
  } catch (error) {
    output.textContent = 'Unable to load regions. Check the data connection and access.';
    console.error(error);
  }
}

render();
```

The example displays the query response for inspection. A finished interface renders the returned rows, handles empty results, and updates queries as controls change. A minimal `styles.css` can contain `body { font-family: system-ui, sans-serif; margin: 1.5rem; }`.

| Runtime API | Role |
| --- | --- |
| `initializeAsync()` | Establishes the extension's Tableau context before other API calls. |
| `workbook.getAllDataSourcesAsync()` | Finds sources connected to the workbook in supported data app environments. |
| Data source `queryAsync()` | Queries Tableau data using the requested fields, aggregations, and filters. |
| Data source `readMetadata()` | Exposes data-source metadata. |
| Extensions API `fetch()` | Makes supported Tableau REST API requests within the site's allowed methods and paths and the viewer's permissions. |

Dashboard placement provides `dashboardContent`; worksheet placement provides `worksheetContent`. The workbook namespace in supported environments supplies workbook-level data access. Opening the HTML outside Tableau does not establish this runtime connection. See the [Extensions API reference](pathname:///api/) for supported method signatures.

### Hosting and access

Tableau hosts the packaged front end; external services remain separate dependencies. The app executes as the viewer, so access to the workbook and access to each published data source are both required. Manifest permissions do not override Tableau permissions or row-level security.

Site controls govern packages, external origins, and Tableau REST API methods and paths. An app's access requirements should identify every external origin and REST operation it needs for administrator review. Passwords, tokens, and fixed copies of sensitive data do not belong in browser resources.

A complete app loads entirely from its published package, reaches its connected sources, and handles loading, empty, error, and restricted-access states. Publishing and subsequent updates require the appropriate destination permissions. Details of site controls and access review are in [Manage Data Apps](./trex_dataapp_manage.md) and [Data App security](./trex_dataapp_security.md). The [Get Started guide](./trex_dataapp_getstarted.md) covers creating the same components with an AI coding assistant.

---

## Data App Samples

_The data apps beta is available only on Tableau Cloud._

The Extensions API repository includes a data app you can open, inspect, and publish.

### Tableau Superstore Data App

**[Tableau Superstore Data App](https://github.com/tableau/extensions-api/tree/main/Samples/DataApp)** rebuilds Tableau's Superstore sample workbook as a data app. The sample is in the `Samples/DataApp` folder. It is a viz extension written in plain JavaScript, and it queries the workbook's data live with `queryAsync()`.

The workbook, the extension package, and the Superstore sample data ship together. The datasource is the Superstore Excel file, stored at `Data/Datasources/Sample - Superstore.xls` and referenced by a relative path, so the workbook publishes to a Tableau Cloud site with its data included.

The app has five tabs. Region and Order Date filters scope every tab.

- **Overview** shows KPIs, a United States choropleth, monthly sales and profit, and selection-driven scope.
- **Product** shows a Category by Year heatmap and a Sub-Category by Segment scatter plot.
- **Customers** shows a region summary, a customer scatter plot, and a ranked customer list.
- **Shipping** classifies orders as Early, On Time, or Late from Order Date and Ship Date, using an expected-transit time for each Ship Mode.
- **Performance** shows Sales against the period average as bar-in-bar small multiples, and a ranked Sub-Category view colored by profit ratio.

The sample requires Tableau 2026.3.1 or later. Publishing steps are in the [sample README](https://github.com/tableau/extensions-api/blob/main/Samples/DataApp/README.md). Publishing uses the [Tableau plugin](https://github.com/tableau/tableau-plugin) and [Tableau MCP](https://github.com/tableau/tableau-mcp).

---

## Get Started with Data Apps

_The data apps beta is available only on Tableau Cloud._

Create a data app by describing what you want to an AI coding assistant. You provide details like the audience, questions, data source, interactions, and visual style. The assistant uses Tableau MCP and the Tableau plugin to connect your data, write the application, and package and publish it to Tableau Cloud. You review the app in Tableau and refine it through conversation.

A data app combines a custom web interface with Tableau data access and hosting. For more about how it works, see [What are Tableau data apps?](./trex_dataapp_overview.md).

### Before you begin

You need:

- Access to a Tableau Cloud site that supports the data apps beta.
- A **Creator** or **Explorer (can publish)** site role and permission to publish to your intended destination.
- A published Tableau data source that you can access. Have its name or link ready.
- An AI client that supports MCP connections, the Tableau plugin, and code execution. The assistant needs to work with local files and run the plugin's scripts.

:::note

Your data app will often make Tableau service API calls to read and modify data and metadata. Your site administrator needs to enable access to each endpoint called for the data app. You may need to prompt your AI coding assistant to list the methods and paths used by the data app and make a request to your administrator.

:::

The workflow uses the `scaffold-data-app`, `publish-workbook`, and `request-workbook-upload` MCP tools, along with tools for finding data sources and reading their metadata. Tool availability depends on your Tableau environment and permissions. Ask the assistant to check these capabilities before it starts building.

### Connect to Tableau MCP

Tableau MCP lets your assistant discover Tableau content, inspect data source metadata, and create and publish the app. Follow the [Tableau MCP getting started guide](https://tableau.github.io/tableau-mcp/docs/getting-started) for connection options.

For Tableau Cloud, use the [hosted Tableau MCP service](https://tableau.github.io/tableau-mcp/docs/hosted-tableau-mcp):

1. Open your AI client's MCP or connector settings and add a connection to `https://mcp.tableau.com`.
2. Complete the Tableau sign-in flow and connect to the site where you want to build the app.
3. Start a new conversation with the connection enabled.

If you install the Tableau plugin first, use its Tableau connector to complete this connection. You do not need a duplicate connection to the same service.

If your organization runs Tableau MCP locally or hosts its own service, follow the configuration instructions in the MCP getting started guide instead.

Check the connection with a prompt such as:

> Find the published data source named Sales on my Tableau site and show me its available fields. Check whether the tools required to scaffold, upload, and publish a data app are available.

If several data sources match, select the one you intend to use before continuing.

:::note

You can also clone the Tableau MCP repo and host the MCP locally instead of using the hosted MCP. Follow the [Tableau MCP getting-started guide](https://tableau.github.io/tableau-mcp/docs/getting-started) for instructions.

:::

### Get the Tableau plugin

The [Tableau plugin](https://github.com/tableau/tableau-plugin) supplies the skills and scripts that guide the assistant through building a data app. Its [data app authoring skill](https://github.com/tableau/tableau-plugin/tree/main/src/plugin/skills/tableau-data-app-authoring) covers scaffolding, connecting a published data source, writing the interface, packaging, and publishing. Install the plugin so the assistant has these resources available.

Follow the repository's [installation instructions](https://github.com/tableau/tableau-plugin#install-locally-codex-and-chatgpt-desktop) for your client. For a local installation from source, first clone the repository:

```bash
git clone https://github.com/tableau/tableau-plugin.git
cd tableau-plugin
```

Then use the installation path for your client:

- **Codex or ChatGPT desktop:** Run `./reload-plugin.sh openai`. This builds and installs the plugin, replacing an existing local Tableau plugin installation. Restart the desktop app, open **Plugins**, and select **Authenticate** or **Connect** for Tableau. Start a new task so it loads the plugin and connection.
- **Claude desktop:** Run `./reload-plugin.sh claude` to build `dist/claude-tableau.zip`. In Claude, open **Customize → Plugins → Add → Upload plugin** and select the ZIP. Open the installed Tableau plugin's **Connectors** tab and connect Tableau. Enable code execution and start a new chat.

The source installation requires Git and Python 3. The build script prepares its build dependencies. See the repository instructions for updates and other installation options.

### Describe the app you want

Tell the assistant to use the Tableau data app authoring skill. Include the app's purpose, audience, published data source, key metrics, controls, visual style, and publishing destination. For example:

> Use the Tableau plugin's data app authoring skill to build a data app called Regional Sales Explorer. Use the published Sales data source on my Tableau Cloud site. The audience is regional sales managers who need to compare sales and profit across regions. Include summary metrics, a ranked regional bar chart, and a region filter. Use a clean layout with blue accents and clear labels. Inspect the data source metadata before choosing fields, and query Tableau data at runtime. Publish it as a new workbook in the Sales Analytics project and give me the link.

Replace the example names with your own. If you do not know which data source to use, ask the assistant to find candidates and help you choose one first.

### Build and publish with the assistant

The assistant follows this workflow:

1. **Check access and tools.** Verify publishing access and the required MCP capabilities.
2. **Create the workspace.** Use `scaffold-data-app` to get a starter and apply its setup plan with the plugin's scripts.
3. **Connect the data source.** Inspect the published source's identity and fields, then connect it to the workbook. The starter alone has no data source connected.
4. **Write the app.** Implement the interface, runtime queries, filters, and loading, empty, and error states from your description.
5. **Package and publish.** Use the plugin's packaging script to create a `.twbx` and publish it through Tableau MCP to your destination.

You do not need to write the application code or assemble the workbook package yourself. If a required tool is unavailable or publishing fails, have the assistant report the missing capability or returned error so you can resolve it before continuing.

### Review and refine in Tableau

Open the published app in Tableau Cloud. Review the layout with real data, try each filter and interaction, and confirm that labels and metrics answer your original questions. Check loading, empty, and error states, and test access as an intended viewer. Visual review happens in Tableau after publishing.

Request specific changes in the same conversation:

> Sort regions by profit instead of sales, add a sales and profit toggle, and use a distinct color for negative profit. Keep the region filter. Update the app and republish it, replacing the workbook we just created.

Before sharing, review the app's code and dependencies and confirm that intended viewers can access both the workbook and its published data source. See [data app security](./trex_dataapp_security.md) for the checks to make before sharing.

---

## Manage Data Apps

The data apps beta is available only on Tableau Cloud.

As a site administrator, you manage data apps through the **Packages** tab on the site's **Settings** page. Data app enablement is configured **per site**. Review and configure these controls for each site where you want users to run data apps.

Data apps include application resources in packages. The Packages tab lets you control the capabilities allowed for packages across the site and disable individual packages when needed.

### Open the Packages tab

1. Sign in to Tableau Cloud as a site administrator and select the site you want to manage.
2. In the navigation pane, select **Settings**.
3. On the site Settings page, select the **Packages** tab.

Within this tab, use the **Settings / Packages** toggle to switch between two views:

- **Settings** controls site-wide package enablement and allowed capabilities.
- **Packages** lists all packages on the site and provides actions for individual packages.

### Configure site-wide package settings

Select **Settings** in the toggle to review the site's package configuration.

![The Packages tab in site Settings, with Settings selected and controls for package enablement, popups, allowed origins, and Tableau REST API access.](../imgs/package-settings.png)

#### Enable packages on the site

Use **Allow Packages on this Site** to control whether packages can run on the selected site. Enable this option when you want to allow data apps on the site.

This is the site-wide control. To disable a specific package while allowing others to run, use the package's Actions menu in the [Packages view](#disable-an-individual-package).

#### Allow popups

Use **Allow Packaged Extensions to trigger popups** to control whether extensions within packages can open popup windows. Review whether your data apps need this capability before allowing it.

#### Control external origins

Under **Extension Package Allowed Origins**, specify the origins from which packages can load resources. Each origin must use HTTPS. Packages that declare a source outside this list will not run.

Use **Add origin** to add an approved origin and the delete control beside an entry to remove it. Review the purpose of each external service and what data the app sends to it. See [data app security](./trex_dataapp_security.md#external-origins).

#### Control Tableau REST API access

The `fetch()` method added to the Extensions API for this release enables data apps to make a curated set of Tableau REST API requests. Under **Tableau REST API Access**, control which of these requests elements of a package can make. Review the operations required by the data apps on your site before approving access.

The **Allow all REST API access (all paths and methods)** option permits access across API paths and methods.

When this option is unchecked, you must explicitly add the REST API requests available to extension code running in packages on the site. Requests outside the allowed list are blocked.

1. Clear **Allow all REST API access (all paths and methods)**.
2. Select **Add path** to add an entry for an allowed request.
3. Specify the request's HTTP method and relative REST API URL path. Add an entry for each request your apps need.
4. Select **Save** to apply the site's configuration.

![Tableau REST API Access with Allow all unchecked, a relative API path entry, and the Add path button.](../imgs/packages-paths.png)

Use the `{api-version}` and `{site-id}` placeholders where appropriate in the path; the site ID is filled in automatically. Other resource ID placeholders must be supplied by the app. Approve only the operations required by your apps.

These settings do not grant users additional Tableau content or data permissions. See [data app security](./trex_dataapp_security.md#tableau-rest-api-access) for guidance on reviewing API access.

When you finish changing the site's settings, select **Save**.

### View the packages on your site

Select **Packages** in the toggle to display a table of all packages on the selected site.

![The Packages view shows the site's packages, their associated workbooks, metadata, and enablement status.](../imgs/package-packages.png)

The table contains the following columns:

| Column | Information |
| --- | --- |
| Name | The package name. |
| Actions | A three-dot menu for actions on the individual package. |
| Workbook | The workbook associated with the package. |
| Package ID | The package identifier. |
| Version | The package version. |
| Author | The package author. |
| Enabled | Whether the package is enabled. |
| Default activation | The package's default activation setting. |
| Extensions | The number of extensions listed for the package. |
| Uploaded | When the package was uploaded. |

Use the workbook and package metadata to identify the application you want to review. Check its enablement status before investigating why a data app is unavailable to users.

### Disable an individual package

To prevent a specific package from running on the site:

1. In the **Packages** view, locate the package in the table.
2. Select the three-dot menu in its **Actions** column.
3. Select **Disable**.
4. Check the package's **Enabled** status to verify the change.

![A package's three-dot Actions menu with the Disable option.](../imgs/packages-actions.png)

Coordinate with the workbook owner when disabling a package so they can address the impact on users. Review the package again when its code, external dependencies, or requested API access changes.

### Related guidance

- [Data app security](./trex_dataapp_security.md)
- [Get Started with data apps](./trex_dataapp_getstarted.md)
- [Data App Details](./trex_dataapp_details.md)

---

## What are Tableau Data Apps?

The data Apps beta is available only on Tableau Cloud.

A **data app** is a purpose-built interactive application built with code to help users explore data, make a decision, or complete a workflow. A data App gives your custom viz or dashboard extension runtime access to governed Tableau data sources through Extensions API and Tableau REST API methods.

Data apps also host your extension's web resources on Tableau service. You build the interface using the Tableau Extensions API and bundle its HTML, JavaScript, CSS, and images inside a packaged workbook (`.twbx`). These resources are embedded in the workbook and published with it. Tableau hosts and serves them when users open the published content, so you do not need a separate web server for the app's front end.

Your data app appears as a workbook in the Tableau Interface. A workbook can contain more than one data app.

:::note Cloud-only Beta

These pages describe data apps for the Cloud-only Beta. Before you begin, check with your administrator that your Tableau Cloud site is configured to allow your app. Supported capabilities depend on your site configuration.

:::

### Components of a Data App

A data app includes:

- An extension manifest (`.trex`) that describes a Dashboard or Viz Extension.
- A web page and the JavaScript, CSS, images, and other resources it needs.
- The Tableau Extensions API JavaScript library, which connects the application to Tableau.
- A package that contains the extension and its resources, bundled with the workbook.

A Tableau Package (`.tpkg`) is a container for application resources and metadata. The package supplies the resources; the data dpp combines them with Tableau data to provide the user experience.

### What can you do with a Data App?

Build an interface tailored to the questions and workflows your users need. For example, you can create a business report with custom charts, a guided exploration of customer activity, or a tool for comparing scenarios.

A data app can query Tableau data at runtime rather than storing a fixed copy of the results in its source code. This lets you reuse your Tableau data layer, including extract refresh processes and row-level security. The results available to each viewer depend on their data access.

You can also adapt an existing web application to use Tableau data and package it for Tableau hosting. Plan the data connections and permissions as part of that migration.

### Extensions API methods for Data Apps

Three methods added to the Extensions API for this release support data apps:

| Method | Purpose |
| --- | --- |
| `queryAsync()` | Gets data from the configured data source asynchronously. |
| `readMetadata()` | Gets a data source's metadata. |
| `fetch()` | Makes a curated set of Tableau REST API requests, subject to the site's allowed API access and the viewing user's permissions. |

For site controls and permission considerations, see [Manage Data Apps](./trex_dataapp_manage.md) and [Data App security](./trex_dataapp_security.md).

### Who can create and view a Data App?

To view a data app, you need:

- View, full data query, and API access to the workbook containing the app
- View, Connect and API access to each published data source the workbook connects to

To create a data app, you need:

- At least Creator or Explorer (can publish) role for the site containing the data app
- Publish and Overwrite (to republish) access to the project for the data app
- View, Connect and API access to each published data source the data app uses
- Administrator site configuration allowing any Tableau REST API paths/methods the data app calls

### How do Data Apps differ from Dashboard and Viz Extensions?

A data app describes the complete application experience. Dashboard and Viz Extensions provide ways to integrate its interface with Tableau.

| Concept | Purpose |
| --- | --- |
| Dashboard Extension | Adds a custom web application to a dashboard zone. |
| Viz Extension | Adds a custom visualization to a worksheet through the Marks card. |
| Data App | Combines a custom, code-authored interface with Tableau hosting and governed data for a decision or workflow. |

Bundling the web resources with a workbook does not change where the interface appears: a packaged Dashboard Extension still appears on a dashboard, and a packaged Viz Extension still appears in a worksheet.

### Hosting and governance

Tableau-hosted front-end resources travel with the workbook, reducing the need to operate a separate web server for the app. This hosting covers the packaged web resources; it does not provide a runtime for your own server-side application code.

Administrators control which external origins and Tableau REST APIs apps can access. Plan those dependencies explicitly and request only the access your app needs. Publishing an app does not grant its viewers additional permissions to Tableau data.

### How is this different from the Tableau Embedding API?

The [Tableau Embedding API](https://help.tableau.com/current/api/embedding_api/en-us/index.html) brings Tableau views into an application or website that you host. Data apps bundle custom application resources with Tableau content so Tableau can host them. Choose the approach that matches where you want users to work and how you want to deploy your application.

### What's next?

Follow [Get Started with Data Apps](./trex_dataapp_getstarted.md), or explore the components and code examples in [Data App Details](./trex_dataapp_details.md).

---

## Data App security

The data apps beta is available only on Tableau Cloud.

Data apps execute custom code in the viewer's browser and query Tableau data at runtime. Review both the code and the access it requires before publishing. Tableau hosting and data permissions provide controls for the app, but app owners still need to review dependencies and how data is used.

:::note Cloud-only Beta

Confirm that the required settings are enabled on your Tableau Cloud site. Available controls and supported capabilities depend on your site configuration. Use the settings provided by your site when approving or disabling an app.

:::

### Content access and data permissions

A data app runs as the viewing user and queries Tableau data at runtime. The `queryAsync()` and `readMetadata()` methods added for this release provide data and metadata access; they do not grant additional data-source permissions. Access to the workbook and access to its data are separate considerations: being able to open an app does not grant additional permissions to its data sources.

Use Tableau content permissions to determine who can publish, view, and manage the workbook. Review the permissions and row-level security on the data sources that power the app. Test with accounts representing the intended audiences, rather than relying on the publisher's experience alone.

Keep security rules in the data layer. Hiding a field or control in the app's interface does not prevent access to data that a query returns. Request only the data needed for the user's task, and avoid embedding a fixed copy of sensitive data in HTML or JavaScript.

### Tableau-hosted resources

The app's HTML, JavaScript, CSS, images, and other front-end resources are embedded in a packaged workbook and served by Tableau. This removes the need to operate a separate web server for those resources and lets you distribute the app with its workbook.

Hosting does not replace code review. Review application code and third-party libraries before publishing, including code generated by an AI agent. The packaged resources run in the viewer's browser; do not place passwords, access tokens, or other secrets in them.

Tableau hosting covers the bundled front-end resources. If the app depends on an external service, that service still requires its own availability, access controls, and approval.

### External origins

An external origin is a combination of protocol, host, and port, such as `https://api.example.com`. Apps declare the external origins needed to load resources or connect to services. Administrators control which origins are allowed.

Before approving an origin, understand what the app uses it for. Loading a charting library from a CDN and sending query results to a third-party API have different implications for your data.

| Dependency | Questions to review |
| --- | --- |
| Scripts and styles | Who maintains the library, and can the required version be bundled with the app? |
| Images, fonts, and other assets | Does the app need to load them externally, or can they be included in the package? |
| Third-party APIs | What information leaves Tableau, where is it sent, and does that use meet your organization's policies? |

Approve only the origins required for the app's intended behavior. Bundling resources where practical reduces external dependencies. An allowed origin does not replace any authentication or browser access requirements imposed by the external service.

### Tableau REST API access

The `fetch()` method added to the Extensions API for this release enables data apps to make a curated set of Tableau REST API requests. Apps declare the Tableau REST API access they require for administrator review. Review these requests separately from external origins: an external dependency does not imply permission to call Tableau APIs.

For each requested API, identify the action the app performs and why it is needed. Give particular attention to operations that create, change, or delete content. Approve only the access required for the workflow.

Declared API access does not grant the viewer additional Tableau permissions. The app must use the supported Extensions API mechanism for Tableau REST requests and remain within the site's approved access.

### Test security before sharing

Test the published app with representative viewer accounts, including users with restricted data access. Confirm that the results respect data-source permissions and row-level security, and that requests stay within the approved external origins and Tableau API access.

Verify that missing permissions and failed queries produce useful messages without exposing sensitive details. Repeat the review when the app changes its data sources, dependencies, or API usage.

### Related guidance

- [Manage data apps](./trex_dataapp_manage.md)
- [Data App Details](./trex_dataapp_details.md)
- [Get Started with data apps](./trex_dataapp_getstarted.md)

---

## Installation


This section will take you through the process of setting up your environment to use one of the sample dashboard or viz extensions. Using one of the sample extensions is a great way to learn and great way to get started developing your own extensions. In this section, you will start a simple web server on your computer to host the samples. You can use the same process for hosting the extension when you start developing your own.

---

:::info

**What's in a Tableau extension?**
A Tableau extension consists of an XML manifest file (`.trex`), an web page (`.html`) that uses a Tableau-provided JavaScript library, and the JavaScript file (`.js`) (or files) that contain your extension logic. The Tableau dashboard and viz extensions are supported on Tableau Server, Tableau Cloud, and Tableau Desktop.

:::

---

#### What you need to get started

If you want to create an extension or work with the sample code, make sure you have the following dependencies installed:

* [Git](https://git-scm.com/downloads)
* [Node.js and npm](https://nodejs.org/en/download/) 

You need Node.js and npm to run the viz and dashboard extension demos. Node.js is a JavaScript runtime. npm is a package manager for Node.js and is installed when you install Node.js.

---

#### Get the Tableau Extensions API SDK

You can get the Tableau Extensions API SDK in two ways. Clone the repository if you want to contribute to the open source project or keep current with the latest changes. Download the `.zip` file if you want to view the samples and work on your own.


* Open a terminal in the directory where you want to copy the Tableau Extensions SDK.  Then run the following command to clone the Tableau Extensions API git repository:

HTTPS

git clone https://github.com/tableau/extensions-api.git


* Open a terminal in the directory where you want to copy the Tableau Extensions SDK.  Then run the following command to clone the Tableau Extensions API git repository:

SSH

`git clone git@github.com:tableau/extensions-api.git`


* Download the [Tableau Extensions API SDK (.zip file)](https://github.com/tableau/extensions-api/archive/main.zip) and extract the files to your computer.


---

#### Requirements for using extensions in Tableau

To use Tableau dashboard extensions, viz extensions, or data apps in Tableau, you need one of the following versions of Tableau. The data apps beta is available only on Tableau Cloud.

For dashboard extensions:

* Tableau Desktop 2018.2 and later
* Tableau Server 2018.2 and later
* Tableau Cloud

For viz extensions:

* Tableau Desktop 2024.1 and later
* Tableau Server 2024.1 and later
* Tableau Cloud

For data apps (Cloud-only Beta):

* Tableau Cloud

#### Security requirements

To run extensions on Tableau Server or Tableau Cloud, support for extensions must be enabled, and depending upon the extension and the data access it requires, the extension might need to be added to the safe list for the site. See
 [Manage Dashboard Extensions on Tableau Server](https://onlinehelp.tableau.com/current/server/en-us/dashboard_extensions_server.htm) or [Manage Dashboard Extensions on Tableau Cloud](https://onlinehelp.tableau.com/current/online/en-us/dashboard_extensions_server.htm) for more information.

Special care must be taken for data apps, available only on Tableau Cloud during the beta, to ensure that security concerns are addressed. See [Manage data apps](./dataapps/trex_dataapp_manage.md) and [data app security](./dataapps/trex_dataapp_security.md) for more information.

---

## Tableau Extension Manifest File

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).  

### Tableau TREX Generator

To create a new manifest file (`.trex`) for your extension the easy way, use the [Tableau TREX Generator](https://trex-generator.glitch.me/) on [Glitch](https://glitch.com). The Tableau TREX Generator allows you to create the manifest file by filing in a form. You can also upload an existing `.trex` file and use that as a starting point. You can use the generator to edit and modify your `.trex` file as needed. When you are finished, just download the file to use with your extension.

### 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.

:::note

Each extension must be uniquely identified. If multiple extensions in a workbook share the same combination of URL, ID, and version number, the extension zones will not load properly. As a best practice, use unique identifiers for each viz or dashboard extension when creating the manifest file (.trex). For example, for dashboard extensions, make sure that the same `<dashboard-extension>` `id` and `extension-version`, and the `<source-location>` `url` aren't all used together in other extensions.

:::

### Error Reporting

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/Logs` folder. This is the same location that Tableau Desktop uses to report other errors and activity.

### Sample Manifest File

```xml
        <?xml version="1.0" encoding="utf-8"?> 
        <manifest manifest-version="0.1" xmlns="http://www.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>Extension Description</description>
            <author name="USERNAME" email="USER@example.com" organization="My Company" website="https://www.example.com"/>
            <min-api-version>1.0</min-api-version>
            <source-location>
              <url>SCHEME://SERVER[:PORT][/PATH]</url> 
            </source-location>
            <icon>Base64-Encoded ICON</icon>
            <permissions>
              <permission>full data</permission>
            </permissions>
            <context-menu>
              <configure-context-menu-item />
            </context-menu>
          </dashboard-extension>
          <resources>
            <resource id="name">
              <text locale="en_US">name in English</text>
              <text locale="fr_BE">name in French</text>
              <text locale="de_DE">name in German</text>
            </resource>
          </resources>
        </manifest>
```

### Elements of the Manifest File

<colgroup>
<col width="30%" />
<col width="70%" />
</colgroup>

Name of element | Description

<code>manifest</code> | The root element that contains the manifest options.

<code>manifest-version</code> | The version of the manifest. The version currently supported is 0.1.

<code>dashboard-extension</code> | 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.

<code>extension-version</code> | The version of the extension. For example, <code>extension-version="0.1.0"</code>

<code>default-locale</code> | 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.

<code>name</code> | 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.

<code>description</code> | A short description of the extension.

<code>author</code> | 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> and <code>website</code> attributes are required. The <code>website</code> URL must use HTTPS. The <code>website</code> URL is the target of the Get Support link that users see in the About dialog box for your extension. The URL should take users to a page where they can learn about your extension and can get help on using it.

<code>source-location</code> | Contains the <code>url</code> of the server that hosts the web page you create that interacts with Tableau.

<code>url</code> | Specifies the scheme (HTTPS, HTTTP), the name of the server, the port (optional) and the path to extension (optional). 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>.

<code>icon</code> | If specified, the icon is what appears in the About dialog box. The icon must be a 70x70 pixel PNG file that is Base64 encoded. If you need an encoder, see https://www.base64-image.de/

<code>permissions</code> | Declares the types of permissions that this extension requires. The only option is <code>full data</code>. If your extension can access the underlying data or information about the data sources, you must declare full data permission in the manifest. Full data permissions are required if you use any one of the following APIs: <code>Worksheet.getUnderlyingDataAsync()</code>, <code>Datasource.getUnderlyingDataAsync()</code>, <code>Datasource.getActiveTablesAsync()</code>, <code>Datasource.getConnectionSummariesAsync()</code>. If your extension does not use one of these APIs, you do not need include permissions element.

<code>context-menu</code> | Adds a context menu item in the extension zone.  This is a configuration feature that allows you to register a custom JavaScript callback function and associate it with a context menu item. The only allowed element in <code>&lt;context-menu&gt;</code> is <code>&lt;configure-context-menu-item /&gt;</code>. The menu item and your configuration callback function are mapped together in the <code>initializeAsync()</code> function. When the extension is initialized, the menu item Configure... appears in the drop-down menu of the dashboard extension. When the user clicks the menu item, your callback function is executed.

<code>resources</code> | Specifies the resources that can be localized.

<code>min-api-version</code> | Specifies the minimum API version required to run the extension.

**Constraints** 

- String-based fields: 1000 characters 
- URI-based fields: 2084 characters
- Icon field: size of images are restricted to 70x70

---

## Tableau Viz Extension Manifest File

The viz extension manifest file (`.trex`) contains metadata for the extension and is used for registration. The manifest file for viz extensions is similar to the file used for dashboard extensions in structure, but instead of the `dashboard-extension` element, you define a `worksheet-extension` element. The manifest files are not interchangeable.

For details about a manifest or its fields, see the [Sample Manifest File](#sample-viz-manifest-file) and [Elements of the Viz Manifest File](#elements-of-the-viz-manifest-file).  

---

### 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.

:::note

Each extension must be uniquely identified. If multiple extensions in a workbook share the same combination of URL, ID, and version number, the extension zones will not load properly. As a best practice, use unique identifiers for each viz or dashboard extension when creating the manifest file (.trex). For example, for viz extensions, make sure that the same `<worksheet-extension>` `id` and `extension-version`, and the `<source-location>` `url` aren't all used together in other extensions.

:::

### Error Reporting

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/Logs` folder. This is the same location that Tableau Desktop uses to report other errors and activity.

### Sample Viz Manifest File

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
  <worksheet-extension id="com.example.extensions.name" extension-version="0.1.0">
    <default-locale>en_US</default-locale>
    <name resource-id="name"/>
    <description>Viz extension description</description>
    <author name="USERNAME" email="USER@example.com" organization="MyCo" website="https://www.example.com"/>
    <min-api-version>1.1</min-api-version>
    <source-location>
      <url>SCHEME:SERVER:PORT/PATH</url>
    </source-location>
    <icon>Base64-Encoded ICON</icon>
    <permissions>
      <permission>full data</permission>
    </permissions>
    <encoding id="Encoding-id">
      <display-name resource-id="encoding-name">Encoding display name</display-name>
      <data-spec>
        <data-type>Encoding-type</data-type>
      </data-spec>
      <role-spec>
        <role-type>Encoding-role</role-type>
      </role-spec>
      <fields max-count="n"/>
      <encoding-icon token="letter-m" />
      <tooltip resource-id="tooltip-id">Default tooltip text for encoding</tooltip>
    </encoding>
  </worksheet-extension>
  <resources>
    <resource id="name">
      <text locale="en_US">name in English</text>
      <text locale="fr_BE">name in French</text>
      <text locale="de_DE">name in German</text>
    </resource>
    <resource id="encoding-name">
      <text locale="en_US">EnglishEncoding</text>
      <text locale="fr_BE">FrenchEncoding</text>
      <text locale="de_DE">GermanEncoding</text>
    </resource>
    <resource id="tooltip-id">
      <text locale="fr_BE">French tooltip text</text>
    </resource>
  </resources>
</manifest>

``````

### Elements of the Viz Manifest File

<colgroup>
<col width="30%" />
<col width="70%" />
</colgroup>

Name of element | Description

<code>manifest</code> | The root element that contains the manifest options.

<code>manifest-version</code> | The version of the manifest. Leave this as version 0.1.

<code>worksheet-extension</code> | The root element that contains the options for the viz extension. The <code>worksheet-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.

<code>extension-version</code> | The version of the your extension. For example, <code>extension-version="0.1.0"</code>

<code>default-locale</code> | 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.

<code>name</code> | The name of the extension as it appears on the Marks card under Viz Extensions. 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.

<code>description</code> | A short description of the extension.

<code>author</code> | 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> and <code>website</code> attributes are required. The <code>website</code> URL must use HTTPS. The <code>website</code> .

<code>source-location</code> | Contains the <code>url</code> of the server that hosts the web page you create that interacts with Tableau.

<code>url</code> | Specifies the scheme (HTTPS, HTTTP), the name of the server, the port (optional) and the path to extension (optional). 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>.

<code>icon</code> | Not currently used. The icon is a 70x70 pixel PNG file that is Base64 encoded. If you need an encoder, see https://www.base64-image.de/

<code>permissions</code> | Declares the types of permissions that this extension requires. The only option is <code>full data</code>. If your extension can access the underlying data or information about the data sources, you must declare full data permission in the manifest. Full data permissions are required if you use any one of the following APIs: <code>Worksheet.getUnderlyingDataAsync()</code>, <code>Worksheet.getUnderlyingTablesAsync()</code>, <code>Worksheet.getUnderlyingTableDataAsync()</code>, <code>Worksheet.getUnderlyingTableDataReaderAsync()</code>, <code>Datasource.getLogicalTables()</code>, <code>Datasource.getLogicalTableData()</code>, <code>Datasource.getUnderlyingDataAsync()</code>, <code>Datasource.getActiveTablesAsync()</code>, <code>Datasource.getConnectionSummariesAsync()</code>. If your extension does not use one of these APIs, you do not need include permissions element. For more information, see Accessing Underlying Data.

<code>encoding</code> | Adds tiles to the Marks card for encoding. This is an optional element. By default, the Detail and Tooltip tiles appear on the Marks card. You can use the encoding element to add additional tiles for the fields you want to encode. See the Encoding section for more information.

<code>resources</code> | Specifies the resources that can be localized.

<code>min-api-version</code> | Specifies the minimum API version required to run the extension.

**Constraints** 

- String-based fields: 1000 characters
- URI-based fields: 2084 characters
- Icon field: size of images are restricted to 70x70

----

### Add encoding in the viz manifest

By default, the viz extension has access to the Detail and Tooltip tiles on the Marks card. You can specify additional encoding tiles for the fields you use in your viz extension by adding `<encoding>` elements. Adding encoding elements is optional.

To add custom encoding, you provide definitions for the encoding in the manifest file. For example, the following XML code defines three encoding tiles: an X and Y encoding for continuous numeric measures, and a text encoding for string values. The value of attribute named `id` inside the `<encoding>` element can be used to map to a variable in your JavaScript code. That code then generates the visualization based upon your data.

```xml

<encoding id="x">
  <display-name>X</display-name>
  <data-spec>
    <data-type>numeric</data-type>
  </data-spec>
  <role-spec>
    <role-type>continuous-measure</role-type>
  </role-spec>
  <fields max-count="1"/>
  <tooltip resource-id="tooltip-x-id">Default tooltip text for X encoding</tooltip>
  <encoding-icon token="letter-x" />
</encoding>
<encoding id="y">
  <display-name>Y</display-name>
  <data-spec>
    <data-type>numeric</data-type>
  </data-spec>
  <role-spec>
    <role-type>continuous-measure</role-type>
  </role-spec>
  <fields max-count="1"/>
  <encoding-icon token="letter-y" />
  <tooltip resource-id="tooltip-y-id">Default tooltip text for Y encoding</tooltip>
</encoding>
<encoding id="text">
  <display-name>Text</display-name>
  <data-spec>
    <data-type>string</data-type>
  </data-spec>
  <encoding-icon token="text" />
  <tooltip>Only tooltip text for TEXT encoding</tooltip>
</encoding>

``````

These encodings are rendered on the Marks card as tiles, with the X, Y and Text icons.

![](../assets/viz_ext_marks_icon.png)

:::note

The Tooltip and Details tiles encoding are always part of a viz extension.

:::

The following table lists the elements and values you can use to add encoding tiles to the Marks card.

<colgroup>
<col width="30%" />
<col width="70%" />
</colgroup>

Name of element | Description

<code>encoding</code> | (Optional) The element that contains the encoding definition. By default, all viz extensions will have the Tooltip and Details encoding tiles. If you want to add your own encoding tile, add this &lt;encoding&gt; element to the manifest file and specify a unique <code>id</code> for the encoding. The <code>id</code> corresponds to a variable in your code that is used to generate the visualization from the data. For example, the encoding with the <code>id</code> of <code>'x'</code> could be used to map fields to the x-axis of the visualization. You can add up to four custom encodings.

<code>display-name</code> | (Required) The text string to display on the encoding tile on the Marks card. You can localize this text string by adding an optional <code>resource-id</code> for the encoding. For example, <code>&lt;display-name resource-id="encoding1"&gt;Encoding Name&lt;display-name&gt;</code>. You provide localized strings for this <code>resource-id</code> in the <code>resources</code> section of the manifest file.

<code>data-spec</code> | (Optional) Includes the list of data types supported by this encoding. If a &lt;data-spec&gt; element is included, only fields of the specified data types are accepted for this encoding. If the <code>data-spec</code> attribute is omitted, all supported data types will be accepted. The supported data types are defined in this table.

<code>data-type</code> | There are four possible data types.
<code>numeric</code>, which supports integer and decimal numeric fields.
<code>temporal</code>, which supports the three temporal related fields, date, time, and date/time.
<code>string</code>, any text string field.
<code>boolean</code>, which supports a boolean (true/false) field.
Geographic and cluster group data types are not supported. For more information, see Data Types in Tableau.

<code>role-spec</code> | (Optional) Includes the list of role types supported by this encoding. Role types correspond to the dimensions and measures in Tableau (indicated by the blue and green pills you place on the visualization). If omitted, all four possible values are supported. For more information, see Dimensions and Measures, Blue and Green.

<code>role-type</code> | (Required) Specifies whether the encoding is for a continuous or discrete dimension or measure. The options are:  <code>continuous-measure</code>, <code>discrete-dimension</code>, <code>continuous-dimension</code>, <code>discrete-measure</code>.

<code>fields</code> | (Optional) The maximum number of fields that can use this encoding. Use the `max-count` attribute to specify the maximum number of fields. If not specified, there is no limit on the number of fields that can use this encoding.

<code>encoding-icon</code> | (Optional) Specify the icon to use in the Encoding tile and next to fields when associated to your encoding. Select from one of the many predefined icons which Tableau offers to Viz Extension developers. If none is specified, the next available default icon which hasn't been used yet will be associated with your encoding. The defaults are the Ⓐ, Ⓑ, Ⓒ, or Ⓓ icons.

<code>tooltip</code> | (Optional) The text string to display as a tooltip when the mouse is hovering over this particular encoding tile. You can localize this tooltip text by adding an optional <code>resource-id</code>.  You provide localized strings for this <code>resource-id</code> in the <code>resources</code> section of the manifest file. With no <code>resource-id</code> xml attribute, the value will be used as the tooltip in all locales.

### Icons

Custom encodings can be assigned a specific icon by using the <code>&lt;encoding-icon&gt;</code> XML tag inside each <code>&lt;encoding&gt;</code> entry in the `.trex` manifest file.

```xml

<encoding-icon token="letter-x" />

```

Note that the `<encoding-icon>` keywords ("`letter-x`", for example) are ids in Tableau associated with specific icons. You should define your own friendly encoding names using the `<display-name>` tag. To help your users, the names you choose for the encoding icons should be related to the viz extension and viz type you are creating. For example, the following snippet uses the encoding icon `token="edge"` (), but labels the icon "Link" to reflect its role in a Sankey visualization.

```xml

<encoding id="edge">
  <display-name resource-id="edge-id">Link</display-name>
  <role-spec>
    <role-type>continuous-measure</role-type>
    <role-type>continuous-dimension</role-type>
  </role-spec>
  <fields max-count="1"/>
  <encoding-icon token="edge" />
  <tooltip resource-id="edge-id">Edge</tooltip>
</encoding>

```

The table shows the list of icons you can use. 
Note that the icons and keywords for the letters "f" through "y" follow the same pattern as the other letters (`token="letter-f"` ). For brevity, they aren't shown in this table.

<colgroup>
<col width="30%" />
<col width="10%" />
<col width="%20" />
<col width="30%" />
<col width="10%" />
</colgroup>

keyword | Icon | &nbsp; | keyword | Icon

color |  | &nbsp; | letter-a | 

size |  | &nbsp; | letter-b | 

text |  | &nbsp; | letter-c | 

line |  | &nbsp; | letter-d | 

shape |  | &nbsp; | letter-e | 

wedge |  | &nbsp; | ... | ..

level-of-detail |  | &nbsp; | letter-z | 

tooltip |  | &nbsp;

level |  | &nbsp; | digit-0 | 

level-radial |  | &nbsp; | digit-1 | 

edge |  | &nbsp; | digit-2 | 

&nbsp; | &nbsp; | &nbsp; | digit-3 | 

dot |  | &nbsp; | digit-4 | 

favorite |  | &nbsp; | digit-5 | 

filter |  | &nbsp; | digit-6 | 

flow |  | &nbsp; | digit-7 | 

forecast |  | &nbsp; | digit-8 | 

globe |  | &nbsp; | digit-9 | 

grid |  | &nbsp; | &nbsp; | &nbsp;

highlight |  | &nbsp; | hash | 

image |  | &nbsp; | dollar | 

join |  | &nbsp; | percentage | 

link |  | &nbsp; | ampersand | 

metric |  | &nbsp; | exclamation | 

delta-down |  | &nbsp; | smaller-than | 

delta-up |  | &nbsp; | equal | 

three-dots |  | &nbsp; | larger-than | 

arrow-down |  | &nbsp; | question | 

arrow-up |  | &nbsp; | at-symbol | 

arrow-left |  | &nbsp; | function | 

arrow-right |  | &nbsp; | &nbsp; | &nbsp;

thumbnail-even |  | &nbsp; | &nbsp; | &nbsp;