Apply Worksheets and Compose Dashboard
Applies a queue of prepared worksheets to the workbook open in Tableau Studio and then composes them into a dashboard, in one ordered pass (apply, then compose). Each queued worksheet is applied in the order you list it; the dashboard is composed last, from those worksheets plus any worksheets already in the workbook that you name. Optional kpiWorksheetNames supplies an ordered KPI strip. If a dashboard of that name already exists, the compose is refused unless you pass replaceExisting: true. The whole queue is checked against live state before the first write, and the pass stops at the first step that fails, reporting a per-step receipt of what landed.
This tool is not read-only and not idempotent. It writes worksheets and a dashboard into the live Tableau Studio session. Passing replaceExisting: true deletes and rebuilds an existing dashboard that shares the name you pass.
APIs called
This tool acts on the workbook open in the local Tableau Studio instance, not on the Tableau Cloud or Tableau Server REST API. Under the hood these are calls to the local Tableau Studio External Client API — a REST API the running Tableau Studio instance serves at http://127.0.0.1:<port>/v<x>, where <x> is the latest API version. There are no OAuth scopes: each call is authorized by the running Tableau Studio instance's per-session bearer token over the loopback interface. Every write in the batch — each worksheet and the dashboard — is a whole-workbook document apply, and each is preceded by a read and followed by a verifying read.
- Reads the open workbook document. A single read up front checks the queue against live state; further reads guard each apply against a workbook that changed underneath it and verify each apply afterwards.
GET /v<x>/workbook/document— retrieve the open workbook document. API reference
- Applies each queued worksheet in order, then the composed dashboard. Replacing an existing dashboard of the same name (
replaceExisting: true) costs two applies (one to remove it, one to add its replacement).POST /v<x>/workbook/document— replace the open workbook from the posted document (Content-Type: application/xml). API reference
- Focuses the sheet each apply produced — the worksheet after a worksheet apply, the dashboard after the compose. This step is best-effort; a failure here does not fail the step that already landed.
POST /v<x>/workbook:goToSheet— activate the sheet the apply produced. API reference
- Claims each queued worksheet and checks it before any write: the worksheet content is validated, its name is checked for collisions, and it is confirmed to belong to this session and this Tableau Studio instance. All in-process; no API call.
Required arguments
dashboardName
Name of the dashboard to compose once the queued worksheets are applied, 1–255 characters. If a dashboard of this name already exists, the compose is refused unless replaceExisting is true.
The name must be unique among sheets: it is rejected before any write if it matches a worksheet already in the workbook or the title of a worksheet in the queue.
Example
{ "dashboardName": "Executive Overview" }
Optional arguments
session
Identifier of the target Tableau Studio session, up to 64 characters. When omitted, the session is resolved automatically (for example, when exactly one Tableau Studio instance is connected).
Example
"studio-1"
artifactIds
Identifiers of prepared worksheets to apply before the dashboard is composed, in the order given. Up to 6 identifiers, each 1–255 characters. These are the identifiers returned when worksheets are built from templates; omit the argument to compose a dashboard purely from worksheets that are already in the workbook.
The worksheet each identifier carries is named by the prepared worksheet itself — you do not name them here, and their names are appended after the names you pass in existingWorksheetNames.
Preparation is single-use and session-bound
A prepared worksheet can be applied once. Once a batch dispatches it, the identifier is consumed and a later call naming it fails. The same applies to an identifier that was never built, that another call is currently applying, or that belongs to a different session or a different Tableau Studio instance. Duplicate identifiers in one call are rejected outright.
All of these are caught in preflight, before any write, so the batch fails with nothing applied and is safe to retry once you build fresh worksheets.
Staleness check
Each prepared worksheet records the state of the workbook it was built against. If the workbook changed in a way that invalidates it, the batch stops in preflight rather than applying content built for a workbook that no longer exists.
Example
{ "artifactIds": ["artifact-1", "artifact-2"] }
existingWorksheetNames
Names of worksheets already in the open workbook to include on the dashboard, up to 6, each 1–255 characters. They are placed ahead of the worksheets that come from artifactIds.
Each name must match a worksheet that is present in the workbook and rendered — that is, one that has its own sheet tab. Names that do not resolve are reported before any write, and the message names them.
Example
{ "existingWorksheetNames": ["Sales by Region"] }
kpiWorksheetNames
Ordered KPI worksheet names to show in a KPI strip, 1–5 names, each 1–255 characters. Optional. Used with the executive-summary layout.
Example
{ "kpiWorksheetNames": ["Sales KPI", "Profit KPI"] }
kpiWorksheetNames requires layoutType "executive-summary". Duplicate KPI worksheet name(s) are refused, and the message names each repeated name. Unknown KPI worksheet name(s) are refused when a name is not one of the worksheets being placed on the dashboard, and the message names each unknown name.
title
Title text rendered as a bold header band across the top of the dashboard, above the worksheets. 1–255 characters. When omitted, no title band is added.
Example
"Executive Overview"
Dashboard "the dashboard name" readback did not match the requested title and layout. The check runs after the dashboard is posted, and the batch reports applied: "unknown" with retrySafe: false. The message names the dashboard.
layoutType
How the worksheets are arranged on the dashboard. One of auto-grid, rows, columns, or executive-summary. Defaults to auto-grid.
auto-grid(default) — worksheets flow left-to-right, top-to-bottom acrossgridColumnscolumns.rows— worksheets stack vertically, each spanning the full width.columns— worksheets sit side by side, each spanning the full height.executive-summary— executive layout; pair withkpiWorksheetNamesfor the ordered KPI strip.
Example
"columns"
layoutType "executive-summary" requires at least one KPI worksheet name. layoutType "executive-summary" requires at least one non-KPI worksheet.
gridColumns
Column count used by the auto-grid layout. Range: 1-6. When omitted, the grid uses the smaller of 2 and the number of worksheets.
Example
2
gridColumns cannot be combined with layoutType "executive-summary".
replaceExisting
Whether to delete and rebuild a dashboard that already has this dashboardName. Defaults to false: if that dashboard already exists, the compose is refused in preflight and nothing is applied. Pass true only for an explicit request to rebuild or replace that dashboard.
replaceExisting does not override a name collision with a worksheet. A dashboard name that matches a worksheet already in the workbook, or a worksheet in the queue, is still rejected before any write.
Example
{ "replaceExisting": true }
Notes and caveats
- Combined worksheet budget. The prepared worksheets and the named existing worksheets together must total between 1 and 6. A queue outside that range, or one whose worksheet names collide with each other, fails in preflight with nothing applied.
- Duplicate worksheet name(s) are refused in preflight, and the message names each repeated name. Nothing is applied.
- Preflight is all-or-nothing; the writes are not. Everything checkable is checked before the first write, so a rejected queue leaves the workbook untouched and is safe to retry. Once writing starts, the batch stops at the first failure: the steps that already landed stay landed, the rest are reported as skipped, and the overall
appliedis"partial". - An uncertain step ends the batch. If a worksheet apply cannot be confirmed — the request may have reached Tableau Studio, or its verification did not pass — the batch reports
applied: "unknown"withretrySafe: falseand does not start the next step. Inspect the live workbook before retrying rather than re-running the call. - Receipts are bounded. Error text and verification messages in the receipt are truncated at 384 characters, so a long failure message from Tableau Studio is reported in abbreviated form.
Example results
Whole batch applied
{
"applied": true,
"retrySafe": false,
"steps": [
{
"index": 0,
"operation": "worksheet",
"artifactId": "artifact-1",
"state": "applied",
"retrySafe": false,
"title": "Profit Trend",
"verification": { "ok": true, "status": "passed" }
},
{
"index": 1,
"operation": "dashboard",
"dashboardName": "Executive Overview",
"state": "applied",
"retrySafe": false,
"worksheets": ["Sales by Region", "Profit Trend"],
"replaced": false,
"verification": { "status": "passed", "issues": [] }
}
]
}
Stopped after a later worksheet failed
{
"applied": "partial",
"retrySafe": false,
"steps": [
{
"index": 0,
"operation": "worksheet",
"artifactId": "artifact-1",
"state": "applied",
"retrySafe": false,
"title": "Profit Trend",
"verification": { "ok": true, "status": "passed" }
},
{
"index": 1,
"operation": "worksheet",
"artifactId": "artifact-2",
"state": "failed",
"retrySafe": true,
"error": "Template artifact \"artifact-2\" was already consumed. Build a fresh artifact."
},
{
"index": 2,
"operation": "dashboard",
"dashboardName": "Executive Overview",
"state": "skipped",
"retrySafe": true,
"reason": "stopped after task 1 failed"
}
]
}
Related
apply-worksheet— applies a single prepared worksheet.