Author Parameter
Adds a new parameter to the workbook open in the local Tableau Studio instance. You supply the parameter's caption, data type, and current value — and, optionally, a fixed list of allowable values — and the tool injects the parameter into a host datasource's Parameters dependency block, then applies that document in place. The session is unchanged.
This tool is not read-only and is not idempotent. It writes the new parameter into the live workbook. Repeating the call with the same caption is rejected as a collision.
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); each call is authorized by that session's per-session bearer token over the loopback interface, and there are no OAuth scopes.
- Reads the open workbook's XML to inventory existing parameters and reject a caption that already exists.
GET /v<x>/workbook/document— read the open workbook's XML. API reference
- Injects a Parameters dependency block onto a host datasource (the optional
datasource, or one the tool selects) and builds the new parameter column. Done in-process; no API call. - Applies the edited workbook document to the running instance and reads it back until the new parameter caption is present.
POST /v<x>/workbook/document— replace the open workbook from the posted document (Content-Type: application/xml). API referenceGET /v<x>/workbook/document— re-read the open workbook's XML to confirm the parameter materialized. API reference
Required arguments
caption
The parameter's display name (its caption in Tableau Studio). Must be non-empty, and must not match the caption of a parameter that already exists in the workbook — a collision is rejected before anything is applied.
Example
"p.Period"
An empty caption is refused with caption empty. A caption that matches a parameter already in the workbook is refused before anything is applied, with caption collision — that parameter already exists; pick a new caption.
value
The parameter's current value, given as a string. This seeds both the parameter's current value and its calculation formula. For string and date parameters the value is quoted automatically; for integer, real, and boolean parameters it is used as-is.
Example
"Month"
Optional arguments
datatype
The parameter's data type. One of integer, real, string, boolean, or date. Defaults to integer.
integer,real,boolean— the value is used unquoted;integerparameters are additionally marked as customized.string,date— the value (and anymembers) are quoted.
Example
"string"
members
An optional list of allowable values for the parameter. When one or more members are supplied, the parameter is created as a list parameter, so only those values are selectable; when omitted, the parameter accepts any value of its data type. Members follow the same quoting as value (quoted for string and date).
Example
{ "members": ["Month", "Quarter", "Year"] }
datasource
Host datasource id or name that should carry the Parameters dependency block. When omitted, the tool selects a host datasource from the open workbook.
Example
"Sample - Superstore"
The host is a datasource other than Parameters.
- A name that matches nothing is refused with
Datasource "<name>" was not found. Candidates: <names>. - A caption shared by more than one datasource is refused with
Datasource caption "<name>" is ambiguous. Use an internal datasource name: <names>. - When
datasourceis omitted and more than one non-Parameters datasource is present, the tool refuses withMultiple datasources found; specify datasource. Candidates: <names>. - When the workbook has no non-Parameters datasource, the tool refuses with
No non-Parameters datasource found.
session
Identifier of the target Tableau Studio session. When omitted, the session is resolved automatically (for example, when it is pinned or exactly one Tableau Studio instance is connected). On success the session is unchanged.
Example
"studio-1"
Notes and caveats
- Applied in place; the session does not change. The parameter is injected into a
<datasource-dependencies datasource='Parameters'>block on a real host datasource and applied through the same document write used by sibling authoring tools. A bare top-level Parameters datasource is not sufficient — Tableau Studio reconstructs Parameters from that dependency block. - Readback must show the new caption. If the apply finishes but the re-read does not contain the new parameter caption, the tool reports that the parameter did not materialize.
Example result
Applied in place
{
"parameterName": "[Parameter 2]",
"caption": "p.Period",
"applied": "in-place",
"session": "12345",
"hint": "parameter created in place; the session is unchanged — continue authoring against the same instance"
}
Related
apply-workbook— apply other edited workbook content to the open Tableau Studio workbook.get-xml— read the current workbook's structure.