> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tableau
> Let Agent Factory agents and Builder automations read and act on Tableau Cloud / Server — REST API 3.x, Metadata GraphQL, VizQL Data Service and Pulse — authenticated with a Personal Access Token.
The Tableau connector exposes the full Tableau platform — REST API 3.x, Metadata GraphQL, VizQL Data Service and Pulse — to your Prisme.ai workspaces. It can be consumed two ways: as a remote MCP server that **Agent Factory** agents call as tools, or as a Builder app whose instructions (`Tableau.`) you call directly from DSUL. Authentication is a Tableau **Personal Access Token** (PAT) you paste into the app configuration; the connector exchanges it server-side for a short-lived `X-Tableau-Auth` session token, so credentials are never exposed to the agent.
Browse, publish, download and govern projects, workbooks, views, datasources and Prep flows. Manage tags, permissions and revisions site-wide.
Manage Tableau Pulse metrics and definitions, retrieve BAN insights, and orchestrate email and Pulse subscriptions for end-users.
Run arbitrary Metadata API GraphQL queries, search assets, walk workbook/datasource lineage and query published datasources via VizQL Data Service.
## Who is this for?
This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.
You build agents in **Agent Factory** and want them to use Tableau. → *Agent builder* tab.
You run the platform and want to know what one-time setup Tableau needs. → *Platform admin setup* accordion below.
You write Builder automations (DSUL) that call `Tableau.` directly. → *Workspace builder* tab.
## Prerequisites
* A **Tableau Cloud** site or a **Tableau Server** installation reachable from Prisme.ai.
* A **Personal Access Token** (PAT) created on the target site under **My Account Settings → Personal Access Tokens**. You need its **name** and its **secret** (the secret is shown only once, at creation).
* The PAT belongs to a Tableau user — that user must exist on the site and own the rights you want to expose (the connector acts as that user).
* The site `contentUrl` if you are not on the *Default* site (the segment after `/site/` in the browser URL).
* Optionally, the **REST API version** to target (defaults to `3.21`; pin only if your Tableau Server release requires it).
**No platform-level credential is required.** Tableau uses the per-workspace credential model: each workspace pastes its own Personal Access Token in the app configuration, and the connector resolves it server-side. There is no shared platform key, no central OAuth client, and no per-user OAuth flow to register.
## Declare the capability in AI Governance (optional)
To let agent builders pick Tableau from the capability catalog instead of pasting an MCP endpoint URL by hand, declare it once as a named capability.
Create (or edit) a **Tableau** capability.
Set the capability's MCP server URL to a Tableau app instance's **MCP Endpoint**, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` in the scope lets the connector identify the calling agent.
Once created, the capability appears in the capability picker for agent builders in your organization. Access to the catalog follows your organization's existing roles; there is no per-capability role grant for this connector.
Declaring the capability makes the connector **discoverable**; the Tableau credentials still live in the workspace that owns the app instance the capability points at. Each workspace that installs Tableau supplies its own PAT — there is no OAuth auth-config JSON to attach in Governance.
***
## Agent builder
**Goal:** let an agent you build in Agent Factory query and act on Tableau through MCP tools.
Before an agent can call the connector, a *Workspace builder* must have installed and configured the Tableau app in a workspace (see the *Workspace builder* tab) so a PAT and an **MCP Endpoint** exist. The *Platform admin setup* accordion above is optional (it only publishes a reusable capability).
The Tableau credential is resolved server-side from the app configuration — never exposed to the agent. Your agent is identified by the `agent_id` that Agent Factory injects through the capability *Scope*.
Follow the *Workspace builder* tab: install **Tableau** in a workspace and paste your Personal Access Token (`patName`, `patSecret`) plus `serverUrl` (and `siteContentUrl` if not the Default site). On install, an **MCP Endpoint** is generated automatically.
In your agent in Agent Factory, add a capability pointing at that workspace's **MCP Endpoint** URL, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
If a *Platform admin* has published a **Tableau** capability in the catalog (see the accordion above), pick it instead — the endpoint and Scope are already wired.
Ask the agent a Tableau question. It calls the relevant tool (`workbooks`, `views`, `vizqlData`, …) and grounds its answer on the result.
## Brief the agent in its system prompt
Wiring the capability is not enough — the agent must know the tools exist and when to use them. Copy-pasteable starter:
```text theme={null}
You have access to the Tableau MCP server. Use it whenever the user asks about Tableau content — workbooks, views, datasources, projects, Prep flows, schedules, jobs, subscriptions, Pulse metrics or insights — or wants to query a published datasource via VizQL Data Service or run a Metadata API GraphQL query. Examples: "List the workbooks in the Marketing project", "Refresh the Sales datasource now", "Show the BAN insight for the Revenue metric", "What datasources feed the Quarterly Review workbook?". Prefer the vizqlData tool for analytical questions (aggregations, top N, filters). Prefer calling the tools directly over guessing, and confirm with the user before any destructive action (delete a workbook, cancel a job, remove a permission).
```
Refine the trigger keywords (site names, project names, business domains, typical user phrasings) so the agent reliably picks up the right intent in your context.
**Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL of the Tableau app instance.
## Available Tools
The Tableau MCP follows a dispatcher pattern: each tool exposes multiple operations selected by an `action` argument. The argument list per action is documented in the tool's own `description`.
### Sites & Users
| Tool | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sites` | Manage Tableau sites (Server-only ops; on Tableau Cloud most actions return 403). Actions: `list`, `create`, `get`, `update`, `delete`, `getRecentlyViewed`. |
| `users` | Manage users on a site. Actions: `list`, `get`, `addToSite`, `update`, `removeFromSite`, `getGroups`. |
| `groups` | Manage user groups. Actions: `list`, `create`, `update`, `delete`, `addUser`, `removeUser`, `getUsers`. |
### Content (Projects, Workbooks, Views)
| Tool | Description |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projects` | Manage Tableau content projects (folders). Actions: `list`, `create`, `update`, `delete`. |
| `workbooks` | Manage workbooks: CRUD, downloads (twb/twbx, PDF, PowerPoint, preview), revisions, connections, permissions, tags. Binary downloads are not inline — call `get` and share `webpageUrl`. |
| `views` | Manage views: image/PDF/CSV/Excel exports, lookup by id or path, server-side data filters, permissions and tags. |
### Datasources & Flows
| Tool | Description |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `datasources` | Manage published datasources: CRUD, downloads, revisions, connections, permissions, tags, immediate extract refresh (`updateNow`). |
| `flows` | Manage Tableau Prep flows: CRUD, run, run history, downloads, connections, permissions. |
### Scheduling, Jobs & Refresh Tasks
| Tool | Description |
| --------------------- | ------------------------------------------------------------------------------------- |
| `schedules` | Server schedules + add workbook/datasource/flow tasks to them. |
| `jobs` | Inspect background jobs: `list`, `get` status, `cancel`. |
| `extractRefreshTasks` | Manage extract refresh tasks (one-shot or scheduled): `list`, `get`, `run`, `delete`. |
### Subscriptions, Webhooks & Favorites
| Tool | Description |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| `subscriptions` | Email subscriptions to views/workbooks. Actions: `list`, `get`, `create`, `update`, `delete`. |
| `webhooks` | Tableau webhooks (event notifications). Actions: `list`, `get`, `create`, `update`, `delete`, `test`. |
| `favorites` | Per-user favorites. Actions: `list`, `add`, `delete`. |
### Tableau Pulse
| Tool | Description |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `metrics` | Pulse metrics (instances). Actions: `list`, `get`, `create`, `delete`. |
| `metricDefinitions` | Pulse metric definitions (templates). Actions: `list`, `get`, `create`, `update`, `delete`. |
| `pulseSubscriptions` | Pulse subscriptions to metrics. Actions: `list`, `create`, `delete`. |
| `insights` | Get a Pulse Basic Analytics Narrative (BAN) insight for a metric. Action: `get`. |
### Metadata & VizQL Data Service
| Tool | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `metadata` | Tableau Metadata API (GraphQL). Actions: `query`, `search`, `workbookLineage`, `datasourceLineage`. |
| `vizqlData` | Query a published datasource via VizQL Data Service — the preferred tool for analytical questions. Actions: `readMetadata`, `queryDatasource`. |
## Output Formats
Every tool accepts an `outputFormat` argument that controls the MCP response shape:
* **`verbose`** (default) — human-readable text for LLM consumption.
* **`structured`** — machine-readable JSON in `structuredContent`.
* **`both`** — both text and structured content.
Binary outputs (workbook/view image, PDF, PowerPoint, crosstab Excel, file downloads) cannot be returned inline. The connector instead returns metadata — call `get` and share the `webpageUrl`, or use `views`/`getData` and `vizqlData` for the underlying data.
## Tool Details
### `workbooks`
```json theme={null}
{
"name": "workbooks",
"arguments": {
"action": "list",
"filter": "projectName:eq:Marketing",
"pageSize": 50
}
}
```
| Parameter | Required | Description |
| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `action` | Yes | One of `list`, `get`, `queryViews`, `getConnections`, `getRevisions`, `queryPermissions`, `publish`, `update`, `updateNow`, `updateConnection`, `delete`, `addPermissions`, `deletePermission`, `addTags`, `deleteTag`, plus the binary `download*` actions. |
| `workbookId` | Conditional | Required for any per-workbook action. |
| `request_payload` | Conditional | Required for `publish`. The workbook XML metadata. |
| `permissions` | Conditional | Required for `addPermissions`. Tableau capabilities granted to grantees. |
| `tags` | Conditional | Required for `addTags`. Tag set object. |
### `views`
```json theme={null}
{
"name": "views",
"arguments": {
"action": "getData",
"viewId": "{{viewId}}",
"viewFilters": { "Region": "EMEA" }
}
}
```
| Parameter | Required | Description |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | Yes | One of `list`, `get`, `getByPath`, `getData`, `getSummaryData`, `queryPermissions`, `addPermissions`, `deletePermission`, `addTags`, `deleteTag`, plus the binary `getImage` / `getPdf` / `getCrosstabExcel`. |
| `viewId` | Conditional | Required for any action targeting a view by id. |
| `viewUrl` | Conditional | Required for `getByPath` (`Workbook/sheets/Sheet`). |
| `viewFilters` | No | Server-side filters for `getData` / `getSummaryData`: `{"Field": "value"}` sent as `vf_=`. |
### `datasources`
```json theme={null}
{
"name": "datasources",
"arguments": {
"action": "updateNow",
"datasourceId": "{{datasourceId}}"
}
}
```
| Parameter | Required | Description |
| -------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | Yes | One of `list`, `get`, `getConnections`, `getRevisions`, `queryPermissions`, `publish`, `update`, `updateNow` (triggers an extract refresh), `updateConnection`, `delete`, `addPermissions`, `deletePermission`, `addTags`, `deleteTag`, plus binary `download*`. |
| `datasourceId` | Conditional | Required for any per-datasource action. |
| `connectionId` | Conditional | Required for `updateConnection`. |
| `datasource` | Conditional | Required for `update`. Datasource settings object. |
### `metadata`
```json theme={null}
{
"name": "metadata",
"arguments": {
"action": "search",
"name": "Sales"
}
}
```
| Parameter | Required | Description |
| ---------------- | ----------- | ------------------------------------------------------------------------- |
| `action` | Yes | One of `query`, `search`, `workbookLineage`, `datasourceLineage`. |
| `query` | Conditional | GraphQL document. Required for `query`. |
| `variables` | No | Variables map for the GraphQL query. |
| `name` | Conditional | Exact-name match used by `search` (the Metadata API has no fuzzy search). |
| `workbookLuid` | Conditional | Required for `workbookLineage`. |
| `datasourceLuid` | Conditional | Required for `datasourceLineage`. |
### `vizqlData`
```json theme={null}
{
"name": "vizqlData",
"arguments": {
"action": "queryDatasource",
"datasource": { "datasourceLuid": "{{datasourceLuid}}" },
"query": {
"fields": [
{ "fieldCaption": "Region" },
{ "fieldCaption": "Sales", "function": "SUM" }
]
}
}
}
```
| Parameter | Required | Description |
| ------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | Yes | `readMetadata` or `queryDatasource`. Always `readMetadata` first to discover exact field captions. |
| `datasource` | Yes | Object with `datasourceLuid` (from `workbooks`/`getConnections` or `datasources`/`list`). |
| `query` | Conditional | Required for `queryDatasource`. Must contain a `fields` array; supports `filters` (SET, QUANTITATIVE\_\*, MATCH, TOP) and aggregation `function` (SUM, AVG, COUNTD, …). |
| `options` | No | `returnFormat` (`OBJECTS` / `ARRAYS`), `debug`. |
### `pulseSubscriptions`
```json theme={null}
{
"name": "pulseSubscriptions",
"arguments": {
"action": "create",
"subscription": {
"metric_id": "{{metricId}}",
"user_id": "{{userId}}"
}
}
}
```
| Parameter | Required | Description |
| ----------------------- | ----------- | -------------------------------------------------------------- |
| `action` | Yes | `list`, `create` or `delete`. |
| `subscription` | Conditional | Required for `create`. Must include `metric_id` and `user_id`. |
| `subscriptionId` | Conditional | Required for `delete`. |
| `metric_id` / `user_id` | No | Filters for `list`. |
## Workspace builder
## Installation
1. Go to **Apps** in your workspace
2. Search for **Tableau** and install it
3. Open the app instance configuration and fill in the Personal Access Token fields (`patName`, `patSecret`, `serverUrl`, and `siteContentUrl` if you are not on the Default site)
## Configuration
| Field | Type | Required | Description |
| ---------------- | --------------- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `serverUrl` | string | Yes | Full URL of the Tableau pod / Server (e.g. `https://10ax.online.tableau.com`). No trailing slash. |
| `siteContentUrl` | string | No | Site identifier from the URL (after `/site/`). Leave empty for the *Default* site on Tableau Server. |
| `patName` | string | Yes | Personal Access Token **name** (My Account Settings → Personal Access Tokens). |
| `patSecret` | string (secret) | Yes | Personal Access Token **secret value**. Stored as a workspace secret. Shown only once at creation. |
| `apiVersion` | string | No | REST API version. Defaults to `3.21`. |
| `mcpEndpoint` | string | Auto-populated on install | Endpoint URL of this app instance's MCP server — give this to the *Agent builder* tab. |
The connector exchanges the PAT for an `X-Tableau-Auth` session token via `POST /api/{apiVersion}/auth/signin` and caches it (\~3h). The auth mode is fixed:
| Auth mode | What you provide | Best for |
| ------------------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
| **Personal Access Token (PAT)** | `patName` + `patSecret` for a Tableau user | All Tableau Cloud and Server setups; no per-user OAuth flow needed |
A Tableau PAT allows a single active session, so a concurrent sign-in elsewhere (a script, another tool, a parallel agent run) revokes the cached token. The connector handles this with a retry-on-401 that forces a fresh sign-in — occasional revocations are transparent.
## Available Instructions
Every instruction resolves credentials from the workspace configuration and reuses the cached `X-Tableau-Auth` session token.
### Sites & Users
| Instruction | Description | Returns |
| ----------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `Tableau.listSites` | List sites the current user can access. `pageNumber`, `pageSize` paginate. | `{ sites: [{ id, name, contentUrl }], pagination }` |
| `Tableau.createSite` | Create a site (Tableau Server only) — `site` = `{ name, contentUrl, adminMode, state }`. | `{ site }` |
| `Tableau.getSite` | Get a site by `key`. | `{ site }` |
| `Tableau.updateSite` | Update site settings — `site`. | `{ site }` |
| `Tableau.deleteSite` | Delete a site by `siteId`. | Empty (HTTP 204) |
| `Tableau.getRecentlyViewed` | Recently viewed content for the current user. | `{ recentlyViewed: { recents } }` |
| `Tableau.listUsers` | List users on the site — `filter`, `sort`, `fields`, pagination. | `{ users: [{ id, name, siteRole }], pagination }` |
| `Tableau.getUser` | Get a user by `userId`. | `{ user }` |
| `Tableau.addUserToSite` | Add a user — `user` = `{ name, siteRole, authSetting }`. | `{ user }` |
| `Tableau.updateUser` | Update a user (`userId`, `user`). | `{ user }` |
| `Tableau.removeUserFromSite` | Remove a user (`userId`, optional `mapAssetsTo`). | Empty (HTTP 204) |
| `Tableau.getUserGroups` | List groups a user belongs to (`userId`). | `{ groups, pagination }` |
| `Tableau.listGroups` | List groups — `filter`, `sort`, pagination. | `{ groups, pagination }` |
| `Tableau.createGroup` | Create a local or AD/SCIM group — `group`, `asJob`. | `{ group }` |
| `Tableau.updateGroup` | Update a group (`groupId`, `group`, `asJob`). | `{ group }` |
| `Tableau.deleteGroup` | Delete a group (`groupId`). | Empty (HTTP 204) |
| `Tableau.addUserToGroup` | Add a user to a group (`groupId`, `user`). | `{ user }` |
| `Tableau.removeUserFromGroup` | Remove a user from a group (`groupId`, `userId`). | Empty (HTTP 204) |
| `Tableau.getGroupUsers` | List users in a group (`groupId`). | `{ users, pagination }` |
### Projects, Workbooks & Views
| Instruction | Description | Returns |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `Tableau.listProjects` | List projects — `filter`, `sort`, pagination. | `{ projects: [{ id, name, parentProjectId }], pagination }` |
| `Tableau.createProject` | Create a project — `project`, `publishSamples`. | `{ project }` |
| `Tableau.updateProject` | Update a project (`projectId`, `project`). | `{ project }` |
| `Tableau.deleteProject` | Delete a project (`projectId`). | Empty (HTTP 204) |
| `Tableau.listWorkbooks` | List workbooks — `filter`, `sort`, `fields`, pagination. | `{ workbooks: [{ id, name, projectId, webpageUrl }], pagination }` |
| `Tableau.getWorkbook` | Get a workbook by `workbookId`. | `{ workbook }` |
| `Tableau.publishWorkbook` | Publish a workbook — file payload + `request_payload` XML, `overwrite`, `asJob`. | `{ workbook }` |
| `Tableau.updateWorkbook` | Update a workbook (`workbookId`, `workbook`). | `{ workbook }` |
| `Tableau.updateWorkbookNow` | Trigger an immediate extract refresh (`workbookId`). | `{ job }` |
| `Tableau.deleteWorkbook` | Delete a workbook (`workbookId`). | Empty (HTTP 204) |
| `Tableau.downloadWorkbook` | Download `.twb` / `.twbx` (`workbookId`, `includeExtract`). | Binary (twb/twbx) |
| `Tableau.downloadWorkbookPdf` | Render workbook as PDF (`workbookId`, `type`, `orientation`, `maxAge`). | Binary (PDF) |
| `Tableau.downloadWorkbookPreviewImage` | Workbook preview image (`workbookId`). | Binary (image) |
| `Tableau.downloadWorkbookPowerPoint` | Export workbook to PowerPoint (`workbookId`, `maxAge`). | Binary (pptx) |
| `Tableau.downloadWorkbookRevision` | Download a specific revision (`workbookId`, `revisionNumber`). | Binary (twb/twbx) |
| `Tableau.getWorkbookRevisions` | List workbook revisions (`workbookId`). | `{ revisions, pagination }` |
| `Tableau.queryViewsForWorkbook` | Views in a workbook (`workbookId`, `includeUsageStatistics`). | `{ views: [{ id, name }] }` |
| `Tableau.getWorkbookConnections` | Data connections of a workbook (`workbookId`). | `{ connections: [{ id, datasource }] }` |
| `Tableau.updateWorkbookConnection` | Update a connection (`workbookId`, `connectionId`, `connection`). | `{ connection }` |
| `Tableau.queryWorkbookPermissions` | Permissions on a workbook (`workbookId`). | `{ permissions }` |
| `Tableau.addWorkbookPermissions` | Grant permissions (`workbookId`, `permissions`). | `{ permissions }` |
| `Tableau.deleteWorkbookPermission` | Revoke one capability (`workbookId`, `granteeType`, `granteeId`, `capabilityName`, `capabilityMode`). | Empty (HTTP 204) |
| `Tableau.addTagsToWorkbook` | Add tags (`workbookId`, `tags`). | `{ tags }` |
| `Tableau.deleteTagFromWorkbook` | Remove a tag (`workbookId`, `tagName`). | Empty (HTTP 204) |
| `Tableau.listViewsForSite` | List views site-wide — `filter`, `includeUsageStatistics`, pagination. | `{ views, pagination }` |
| `Tableau.getView` | Get a view by `viewId` (returns `webpageUrl`). | `{ view }` |
| `Tableau.getViewByPath` | Resolve a view by URL path (`viewUrl`). | `{ view }` |
| `Tableau.getViewImage` | Render a view as PNG (`viewId`, `resolution`, `maxAge`). | Binary (image) |
| `Tableau.getViewPdf` | Render a view as PDF (`viewId`, `type`, `orientation`, `maxAge`). | Binary (PDF) |
| `Tableau.getViewData` | View underlying data as CSV (`viewId`, server-side `viewFilters`). | CSV text |
| `Tableau.getViewCrosstabExcel` | View crosstab as Excel (`viewId`, `maxAge`). | Binary (xlsx) |
| `Tableau.getViewSummaryData` | View summary data as CSV (`viewId`). | CSV text |
| `Tableau.queryViewPermissions` | Permissions on a view (`viewId`). | `{ permissions }` |
| `Tableau.addViewPermissions` | Grant permissions (`viewId`, `permissions`). | `{ permissions }` |
| `Tableau.deleteViewPermission` | Revoke one capability (`viewId`, `granteeType`, `granteeId`, `capabilityName`, `capabilityMode`). | Empty (HTTP 204) |
| `Tableau.addTagsToView` | Add tags (`viewId`, `tags`). | `{ tags }` |
| `Tableau.deleteTagFromView` | Remove a tag (`viewId`, `tagName`). | Empty (HTTP 204) |
### Datasources & Flows
| Instruction | Description | Returns |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `Tableau.listDatasources` | List published datasources — `filter`, `sort`, pagination. | `{ datasources: [{ id, name, projectId }], pagination }` |
| `Tableau.getDatasource` | Get a datasource by `datasourceId`. | `{ datasource }` |
| `Tableau.publishDatasource` | Publish a datasource — file payload + `request_payload`, `overwrite`, `append`, `asJob`. | `{ datasource }` |
| `Tableau.updateDatasource` | Update a datasource (`datasourceId`, `datasource`). | `{ datasource }` |
| `Tableau.updateDatasourceNow` | Trigger an immediate extract refresh (`datasourceId`). | `{ job }` |
| `Tableau.deleteDatasource` | Delete a datasource (`datasourceId`). | Empty (HTTP 204) |
| `Tableau.downloadDatasource` | Download `.tds` / `.tdsx` (`datasourceId`, `includeExtract`). | Binary (tds/tdsx) |
| `Tableau.downloadDatasourceRevision` | Download a specific revision (`datasourceId`, `revisionNumber`). | Binary (tds/tdsx) |
| `Tableau.getDatasourceRevisions` | List revisions (`datasourceId`). | `{ revisions, pagination }` |
| `Tableau.getDatasourceConnections` | Data connections (`datasourceId`). | `{ connections }` |
| `Tableau.updateDatasourceConnection` | Update a connection (`datasourceId`, `connectionId`, `connection`). | `{ connection }` |
| `Tableau.queryDatasourcePermissions` | Permissions on a datasource (`datasourceId`). | `{ permissions }` |
| `Tableau.addDatasourcePermissions` | Grant permissions (`datasourceId`, `permissions`). | `{ permissions }` |
| `Tableau.deleteDatasourcePermission` | Revoke one capability (`datasourceId`, `granteeType`, `granteeId`, `capabilityName`, `capabilityMode`). | Empty (HTTP 204) |
| `Tableau.addTagsToDatasource` | Add tags (`datasourceId`, `tags`). | `{ tags }` |
| `Tableau.deleteTagFromDatasource` | Remove a tag (`datasourceId`, `tagName`). | Empty (HTTP 204) |
| `Tableau.listFlows` | List Prep flows — `filter`, `sort`, pagination. | `{ flows, pagination }` |
| `Tableau.getFlow` | Get a flow by `flowId`. | `{ flow }` |
| `Tableau.downloadFlow` | Download a flow file (`flowId`). | Binary (tfl/tflx) |
| `Tableau.deleteFlow` | Delete a flow (`flowId`). | Empty (HTTP 204) |
| `Tableau.runFlow` | Start a flow run (`flowId`, `flowRunSpec`). | `{ flowRun }` |
| `Tableau.getFlowRunStatus` | Status of a flow run (`flowRunId`). | `{ flowRun }` |
| `Tableau.listFlowRuns` | List flow runs — `filter`, pagination. | `{ flowRuns, pagination }` |
| `Tableau.getFlowConnections` | Connections of a flow (`flowId`). | `{ connections }` |
| `Tableau.queryFlowPermissions` | Permissions on a flow (`flowId`). | `{ permissions }` |
| `Tableau.addFlowPermissions` | Grant permissions (`flowId`, `permissions`). | `{ permissions }` |
| `Tableau.deleteFlowPermission` | Revoke one capability (`flowId`, `granteeType`, `granteeId`, `capabilityName`, `capabilityMode`). | Empty (HTTP 204) |
### Scheduling, Jobs & Refresh Tasks
| Instruction | Description | Returns |
| ---------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------- |
| `Tableau.listSchedules` | List server-wide schedules (pagination). | `{ schedules, pagination }` |
| `Tableau.getSchedule` | Get a schedule (`scheduleId`). | `{ schedule }` |
| `Tableau.createSchedule` | Create a server schedule — `schedule` = `{ name, priority, type, frequency, frequencyDetails }`. | `{ schedule }` |
| `Tableau.updateSchedule` | Update a schedule (`scheduleId`, `schedule`). | `{ schedule }` |
| `Tableau.deleteSchedule` | Delete a schedule (`scheduleId`). | Empty (HTTP 204) |
| `Tableau.addWorkbookToSchedule` | Add a workbook task to a schedule (`scheduleId`, `task`). | `{ task }` |
| `Tableau.addDatasourceToSchedule` | Add a datasource task to a schedule (`scheduleId`, `task`). | `{ task }` |
| `Tableau.addFlowTaskToSchedule` | Add a flow run task to a schedule (`scheduleId`, `task`). | `{ task }` |
| `Tableau.listJobs` | List background jobs — `filter`, pagination. | `{ backgroundJobs, pagination }` |
| `Tableau.getJob` | Get a job's status (`jobId`). | `{ job }` |
| `Tableau.cancelJob` | Cancel a running job (`jobId`). | Empty (HTTP 204) |
| `Tableau.listExtractRefreshTasks` | List extract refresh tasks (pagination). | `{ tasks, pagination }` |
| `Tableau.getExtractRefreshTask` | Get an extract refresh task (`taskId`). | `{ task }` |
| `Tableau.runExtractRefreshTask` | Run an extract refresh task now (`taskId`). | `{ job }` |
| `Tableau.deleteExtractRefreshTask` | Delete an extract refresh task (`taskId`). | Empty (HTTP 204) |
### Subscriptions, Webhooks & Favorites
| Instruction | Description | Returns |
| ------------------------------ | -------------------------------------------------------------------------------- | ------------------------------- |
| `Tableau.listSubscriptions` | List subscriptions — `filter`, pagination. | `{ subscriptions, pagination }` |
| `Tableau.getSubscription` | Get a subscription (`subscriptionId`). | `{ subscription }` |
| `Tableau.createSubscription` | Create a subscription — `subscription` = `{ subject, content, schedule, user }`. | `{ subscription }` |
| `Tableau.updateSubscription` | Update a subscription (`subscriptionId`, `subscription`). | `{ subscription }` |
| `Tableau.deleteSubscription` | Delete a subscription (`subscriptionId`). | Empty (HTTP 204) |
| `Tableau.listWebhooks` | List webhooks (pagination). | `{ webhooks }` |
| `Tableau.getWebhook` | Get a webhook (`webhookId`). | `{ webhook }` |
| `Tableau.createWebhook` | Create a webhook — `webhook` = `{ name, event, destination }`. | `{ webhook }` |
| `Tableau.updateWebhook` | Update a webhook (`webhookId`, `webhook`). | `{ webhook }` |
| `Tableau.deleteWebhook` | Delete a webhook (`webhookId`). | Empty (HTTP 204) |
| `Tableau.testWebhook` | Fire a test event for a webhook (`webhookId`). | `{ webhookTestResult }` |
| `Tableau.listFavoritesForUser` | List a user's favorites (`userId`). | `{ favorites }` |
| `Tableau.addFavorite` | Add a favorite (`userId`, `favorite`). | `{ favorites }` |
| `Tableau.deleteFavorite` | Remove a favorite (`userId`, `contentType`, `contentId`). | Empty (HTTP 204) |
### Tableau Pulse
| Instruction | Description | Returns |
| --------------------------------- | ------------------------------------------------------------------------ | ------------------------------------ |
| `Tableau.listMetrics` | List Pulse metrics — `definition_id`, `page_size`, `page_token`. | `{ metrics, next_page_token }` |
| `Tableau.getMetric` | Get a Pulse metric (`metricId`). | `{ metric }` |
| `Tableau.createMetric` | Create a Pulse metric — `metric` = `{ definition_id, specification }`. | `{ metric }` |
| `Tableau.deleteMetric` | Delete a Pulse metric (`metricId`). | Empty (HTTP 204) |
| `Tableau.listMetricDefinitions` | List Pulse metric definitions — `view`, `page_size`, `page_token`. | `{ definitions, next_page_token }` |
| `Tableau.getMetricDefinition` | Get a metric definition (`definitionId`, `view`). | `{ definition }` |
| `Tableau.createMetricDefinition` | Create a metric definition — `definition` = `{ name, specification }`. | `{ definition }` |
| `Tableau.updateMetricDefinition` | Update a metric definition (`definitionId`, `definition`). | `{ definition }` |
| `Tableau.deleteMetricDefinition` | Delete a metric definition (`definitionId`). | Empty (HTTP 204) |
| `Tableau.getInsight` | Get a Pulse BAN insight — `bundle_request`. | `{ bundle_response }` |
| `Tableau.listPulseSubscriptions` | List Pulse subscriptions — `metric_id`, `user_id`, paging. | `{ subscriptions, next_page_token }` |
| `Tableau.createPulseSubscription` | Create a Pulse subscription — `subscription` = `{ metric_id, user_id }`. | `{ subscription }` |
| `Tableau.deletePulseSubscription` | Delete a Pulse subscription (`subscriptionId`). | Empty (HTTP 204) |
### Metadata & VizQL Data Service
| Instruction | Description | Returns |
| ------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------- |
| `Tableau.metadataQuery` | Execute an arbitrary Metadata API GraphQL query (`query`, `variables`). | `{ data }` (GraphQL response) |
| `Tableau.searchAssets` | Find workbooks/datasources by exact name (`name`, `first`). | `{ data: { … } }` |
| `Tableau.getWorkbookLineage` | Upstream lineage of a workbook (`workbookLuid`). | `{ data: { workbooks } }` |
| `Tableau.getDatasourceLineage` | Upstream/downstream lineage of a datasource (`datasourceLuid`). | `{ data: { publishedDatasources } }` |
| `Tableau.readMetadata` | VizQL: discover field captions of a datasource (`datasource`, `options`). | `{ data: [{ fieldCaption, dataType }] }` |
| `Tableau.queryDatasource` | VizQL: query a published datasource (`datasource`, `query`, `options`). | `{ data: [{ … }] }` |
`Returns` shows the shape of the operation output. Binary instructions (`download*`, `getViewImage`, `getViewPdf`, `getViewCrosstabExcel`) return file content, not JSON.
## DSUL Examples
### List the workbooks in a project
```yaml theme={null}
- Tableau.listWorkbooks:
filter: 'projectName:eq:Marketing'
pageSize: 50
output: workbooks
```
### Trigger an immediate extract refresh on a datasource
```yaml theme={null}
- Tableau.updateDatasourceNow:
datasourceId: '{{datasourceId}}'
output: refreshJob
- Tableau.getJob:
jobId: '{{refreshJob.job.id}}'
output: jobStatus
```
### Search assets and walk the workbook lineage
```yaml theme={null}
- Tableau.searchAssets:
name: 'Sales Performance'
first: 10
output: matches
- Tableau.getWorkbookLineage:
workbookLuid: '{{matches.0.luid}}'
output: lineage
```
### Query a published datasource via VizQL Data Service
```yaml theme={null}
- Tableau.queryDatasource:
datasource:
datasourceLuid: '{{datasourceLuid}}'
query:
fields:
- fieldCaption: 'Region'
- fieldCaption: 'Sales'
function: 'SUM'
output: rows
```
### Create a Pulse subscription for a user
```yaml theme={null}
- Tableau.createPulseSubscription:
subscription:
metric_id: '{{metricId}}'
user_id: '{{userId}}'
output: subscription
```
***
## Error Handling
| HTTP code | Meaning | Typical cause |
| --------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | Bad Request | Missing or malformed `action`, invalid filter, missing required parameter for the chosen action. |
| 401 | Unauthorized | The PAT was rejected or the session token expired/was revoked. Check `patName` / `patSecret`; a concurrent sign-in with the same PAT revokes the session. |
| 403 | Forbidden | The PAT's user lacks the right, or the action is Tableau Server-only and you are on Tableau Cloud (e.g. site CRUD). |
| 404 | Not Found | The targeted resource does not exist on this site, or `siteContentUrl` is wrong. |
| 409 | Conflict | Trying to `publish` over an existing asset without `overwrite: true`, or a name collision. |
| 429 | Too Many Requests | Tableau API rate limit hit. Retry with exponential backoff. |
| 500 | Internal Server Error | Transient Tableau Server error. Retry; if it persists, check the Tableau status page. |
### Common Issues
**"Tableau auth not configured"** — The app instance has no PAT. Create a Personal Access Token on your Tableau site (My Account Settings → Personal Access Tokens) and paste `patName`, `patSecret` and `serverUrl` in the app configuration.
**"Tableau signin failed (401)"** — The provided PAT was rejected by Tableau, or the cached session was revoked. A Tableau PAT allows only one active session, so a parallel sign-in (a script, another tool) invalidates it. Re-copy the secret, or retry — the connector forces a fresh sign-in on a 401.
**"Site not found" / wrong site** — Check `siteContentUrl`. On Tableau Cloud it is the segment after `/site/` in the browser URL; on Tableau Server's *Default* site, leave it empty.
**Tableau Server-only operation on Tableau Cloud** — Several site- and schedule-management actions (`sites.create`, `sites.update`, `schedules.create`, …) are only available on Tableau Server and return `403` on Tableau Cloud. Check the Tableau REST API reference for the current allow-list.
**VizQL `queryDatasource` returns `403 "API access permission"`** — A Tableau administrator must grant **API Access** on the published datasource before the VizQL Data Service can query it.
## External Resources
Official documentation for the Tableau REST API 3.x, Metadata API, VizQL Data Service and Pulse.
Learn how Agent Factory agents consume MCP tools and capabilities in Prisme.ai.