Format Worksheets
Sets mark labels and number formats on worksheets in the workbook open in Tableau Studio. One call can format up to 12 worksheets, and each entry carries its own list of fields to format, so a set of sheets can be brought to one number-format convention in a single request. Every requested worksheet is read and prepared before the first change is written, and a worksheet that already carries the requested formatting is left untouched.
APIs called
This tool acts on worksheets in the workbook open in the running 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. A workbook must be open in the target session.
- Settles on which Tableau Studio session to target before anything is sent. Resolved in-process (not an External Client API call).
- Reads the worksheet inventory of the open workbook so each requested name or id can be matched to one worksheet. Requires a connected Tableau Studio session with an open workbook; authorized by that session's loopback bearer token. When a match refuses, no further calls are made.
GET /v<x>/workbook/worksheets— list the worksheets in the open workbook. API reference
- Reads each matched worksheet so the requested formatting can be composed against the fields that worksheet actually uses.
GET /v<x>/workbook/worksheets/{id}/document— read that worksheet's document. API reference
- Composes the label and number formatting and matches each requested field to a field the worksheet uses. Done in-process (not an External Client API call). Every requested worksheet is prepared this way first, so a request that cannot be satisfied is refused before any worksheet is written.
- Writes each formatted worksheet back, one worksheet at a time. Immediately before each write the worksheet is re-read and compared against what was prepared, so a worksheet that changed in the meantime is not overwritten. Writes are serialized against other sheet edits so the two cannot interleave.
GET /v<x>/workbook/worksheets/{id}/document— re-read the worksheet to confirm it has not changed since it was prepared. API referencePOST /v<x>/workbook/worksheets/{id}/document(Content-Type: application/xml) — replace that worksheet with the formatted document. API reference
- Re-reads each written worksheet until the requested formatting is present and no intent-bearing structure of the worksheet was dropped, retrying briefly because the change settles asynchronously.
GET /v<x>/workbook/worksheets/{id}/document— re-read the applied worksheet to verify the formatting landed. API reference
Required arguments
worksheets
The worksheets to format, and the formatting to set on each. Type: array of objects. Range: 1-12 entries. Each entry names one worksheet and sets mark labels, number formats, or both on it; the worksheets are formatted in the order given.
Example
{
"worksheets": [
{
"name": "Sales by Category",
"showLabels": true,
"numberFormats": [
{ "field": "Sales", "kind": "currency", "currencySymbol": "$", "decimals": 1, "displayUnits": "millions" }
]
},
{
"name": "Margin by Segment",
"numberFormats": [{ "field": "Margin", "kind": "percentage", "decimals": 1 }]
}
]
}
name
Name or id of the worksheet to format. Type: string. Range: 1-255 characters after surrounding whitespace is trimmed. The tool matches against the live worksheet inventory: an exact id match wins; otherwise an exact name match. A name that matches more than one worksheet is refused and the tool asks you to pass an id; a name or id that matches nothing is refused with the worksheets that are available.
Two entries that resolve to the same worksheet are refused with Worksheet targets must not contain duplicates., and nothing is written. The check runs after every name or id has been matched, so naming one worksheet by name in one entry and by id in another is refused too.
showLabels
Whether mark labels are shown on the worksheet. Type: boolean. Optional. true turns labels on, false turns them off. Omit it to leave the worksheet's current label setting alone.
A worksheet with no chart pane to label is refused with The worksheet has no pane to format., and nothing is written.
numberFormats
Number formats to set on fields of this worksheet. Type: array of objects. Range: 1-12 entries. Optional. Each entry formats one field:
field— the field to format, given as it appears on the worksheet (for exampleSales). Range: 1-255 characters after trimming. Matched case-insensitively against the fields the worksheet uses, tolerating surrounding brackets; the exact shelf field string is accepted as wellkind— the kind of format. One ofnumber,currency, orpercentagedecimals— how many decimal places to show. Integer. Range: 0-2. Defaults to0displayUnits— the scale values are shown in:none,thousands(K),millions(M), orbillions(B). Defaults tonone. Not allowed withkind: "percentage"currencySymbol— the currency symbol to show. One of$,€,£,¥. Required withkind: "currency", and allowed only there
Where the field is used on the worksheet decides where its format lands: a field used as a mark value is formatted on the marks, a field on Rows or Columns is formatted on its labels, and a field used both ways is formatted in both places.
The tool refuses, without writing to any worksheet, when:
kindiscurrencyand nocurrencySymbolis given —currencySymbol is required for currency formatscurrencySymbolis given for anumberorpercentageformat —currencySymbol is only allowed for currency formatsdisplayUnitsis given for apercentageformat —displayUnits is not allowed for percentage formatsfieldmatches more than one of the fields the worksheet uses —Field "<field>" matches more than one field used by this worksheet. Use one exact canonical field reference: <candidates>.fieldis not one of the fields the worksheet uses —Field "<field>" is not used by this worksheet. Available fields: <fields>.(orAvailable fields: none.)fieldis used by the worksheet but neither as a mark value nor on one of its shelves —Field "<field>" is not used as a mark value or on a worksheet shelf.
An entry in worksheets that sets neither showLabels nor numberFormats is rejected with Each worksheet needs showLabels, numberFormats, or both.
Optional arguments
session
Identifier of the target Tableau Studio session; optional if a session is pinned or only one is connected. When omitted, the session is resolved automatically (for example, when exactly one Tableau Studio instance is connected or a session has been pinned).
Example
"studio-1"
With no session given and no Tableau Studio instance running, or more than one running, the tool reports an error rather than picking one; the multiple-instance error lists the session IDs to choose from. A session that names an instance which is not among the running ones is refused the same way.
Notes and caveats
- Not read-only, but idempotent. The tool changes live worksheets, so it is not a read-only operation; running the same request again is safe. A worksheet that already carries every piece of formatting the request asks for is skipped — it is reported as formatted without being written to.
- Worksheets are written one at a time, and partial progress is reported. When a worksheet fails part-way through a multi-worksheet request, the error says how many earlier worksheets may already be updated (for example,
1 earlier worksheet may already be updated.) rather than leaving you to guess. Re-running the same request then formats only what is left, because the worksheets that already landed are skipped. - A worksheet that changes mid-request is not overwritten. If a worksheet is edited between being prepared and being written, the tool reports that the worksheet
changed while formatting was being applied— along with the earlier-updates count — instead of overwriting the newer work. - Formatting is verified by reading the worksheet back. After a write is accepted, the tool re-reads the worksheet and checks both that the requested formatting is present and that no intent-bearing structure of the worksheet was lost. When it is not, the tool reports that the formatting
did not survive readback or Tableau dropped worksheet semanticsrather than claiming success.
Example result
The tool reports one entry per requested worksheet, in the order they were given. A worksheet that was skipped because it already carried the requested formatting is reported the same way as one that was just changed.
{
"formatted": [
{ "worksheet": "Sales by Category", "verified": true },
{ "worksheet": "Margin by Segment", "verified": true }
]
}
Related
sort-worksheet— applies or clears a native field sort on a worksheet, without opening the sort dialog.refine-worksheet— bounded top-N and computed-sort edits on worksheet structure.apply-worksheet— replaces a worksheet with authored content when the change is more than labels and number formats.get-sheets— lists worksheet names and ids in the open workbook so eachnameyou pass resolves to one worksheet.format-dashboard-zones— the dashboard-side counterpart, for formatting zones rather than worksheet marks and labels.