API reference
Important: More coming soon! This section is under active construction and might not reflect all the available functionality of the TSC library.
The Tableau Server Client (TSC) is a Python library for the Tableau Server REST API. Using the TSC library, you can manage and change many of the Tableau Server and Tableau Cloud resources programmatically. You can use this library to create your own custom applications.
The TSC API reference is organized by resource. The TSC library is modeled after the REST API. The methods, for example, workbooks.get(), correspond to the endpoints for resources, such as workbooks, users, views, and data sources. The model classes (for example, the WorkbookItem class have attributes that represent the fields (name, id, owner_id) that are in the REST API request and response packages, or payloads.
| Note: Some methods and features provided in the REST API might not be currently available in the TSC library (and in some cases, the opposite is true). In addition, the same limitations apply to the TSC library that apply to the REST API with respect to resources on Tableau Server and Tableau Cloud. For more information, see the Tableau Server REST API Reference. See also Known server-side limitations below for behaviors that TSC cannot work around because they are constrained by the Tableau Server REST API itself. |
Authentication
You can use the TSC library to sign in and sign out of Tableau Server and Tableau Cloud. The credentials for signing in are defined in the TableauAuth class and they correspond to the attributes you specify when you sign in using the Tableau Server REST API.
TableauAuth class
TableauAuth(username, password, site_id='', user_id_to_impersonate=None)
The TableauAuth class defines the information you can set in a sign-in request. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the Auth.sign_in method.
Note: In the future, there might be support for additional forms of authorization and authentication (for example, OAuth).
Attributes
| Name |
Description |
username |
The name of the user whose credentials will be used to sign in. |
password |
The password of the user. |
site_id |
This corresponds to the contentUrl attribute in the Tableau REST API. The site_id is the portion of the URL that follows the /site/ in the URL. For example, “MarketingTeam” is the site_id in the following URL MyServer/#/site/MarketingTeam/projects. To specify the default site on Tableau Server, you can use an empty string '' (single quotes, no space). For Tableau Cloud, you must provide a value for the site_id. |
user_id_to_impersonate |
Specifies the id (not the name) of the user to sign in as. |
Source file: models/tableau_auth.py
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
server = TSC.Server('https://SERVER_URL', use_server_version=True)
server.auth.sign_in(tableau_auth)
PersonalAccessTokenAuth class
PersonalAccessTokenAuth(token_name, personal_access_token, site_id='')
The PersonalAccessTokenAuth class serves the same purpose and is used in the same way as TableauAuth, but using Personal Access Tokens instead of username and password.
Attributes
| Name |
Description |
token_name |
The personal access token name. |
personal_access_token |
The personal access token value. |
site_id |
This corresponds to the contentUrl attribute in the Tableau REST API. The site_id is the portion of the URL that follows the /site/ in the URL. For example, “MarketingTeam” is the site_id in the following URL MyServer/#/site/MarketingTeam/projects. To specify the default site on Tableau Server, you can use an empty string '' (single quotes, no space). For Tableau Cloud, you must provide a value for the site_id. |
Source file: models/personal_access_token_auth.py
Example
import tableauserverclient as TSC
tableau_auth = TSC.PersonalAccessTokenAuth('TOKEN-NAME', 'TOKEN-VALUE', site_id='CONTENTURL')
server = TSC.Server('https://SERVER_URL', use_server_version=True)
server.auth.sign_in(tableau_auth)
Auth methods
The Tableau Server Client provides two methods for interacting with authentication resources. These methods correspond to the sign in and sign out endpoints in the Tableau Server REST API.
Source file: server/endpoint/auth_endpoint.py
See Also
Sign in and Out
Server
auth.sign_in
Signs you in to Tableau Server.
The method signs into Tableau Server or Tableau Cloud and manages the authentication token. You call this method from the server object you create. For information about the server object, see Server. The authentication token keeps you signed in for 240 minutes, or until you call the auth.sign_out method. Before you use this method, you first need to create the sign-in request (auth_req) object by creating an instance of the TableauAuth. To call this method, create a server object for your server. For more information, see Sign in and Out.
REST API: Sign In
Parameters
auth_req : The TableauAuth object that holds the sign-in credentials for the site.
Example
import tableauserverclient as TSC
# create an auth object
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# create an instance for your server
server = TSC.Server('https://SERVER_URL')
# call the sign-in method with the auth object
server.auth.sign_in(tableau_auth)
auth.sign_out
Signs you out of the current session.
The sign_out() method takes care of invalidating the authentication token. For more information, see Sign in and Out.
REST API: Sign Out
Example
auth.switch_site
auth.switch_site(site_id)
Switch to a different site on the current Tableau Server.
Switching avoids the need for reauthenticating to the same server. (Note: This method is not available in Tableau Cloud.)
REST API: Switch Site
Parameters
site_item |
The site that you want to switch to. This should be a SiteItem retrieved from sites.get(), sites.get_by_id() or sites.get_by_name{}. |
Example
# find and then switch auth to another site on the same server
site = server.sites.get_by_id('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')
server.auth.switch_site(site)
See Also
Sign in and Out
Server
Auth Federation
Using the Tableau Server Client (TSC), a Site Administrator can enable Workload Identity Federation (WIF) on a Tableau Cloud / Tableau Server site, manage the signing keys that mint JWTs for cloud-provider federation, and register the connectors (for example, BigQuery or Snowflake) that each JWT is scoped to.
The WIF admin resources are defined in the AuthFederationItem, AuthFederationConnectorItem, and AuthFederationKeyItem classes. These correspond to the admin resources exposed by the Tableau REST API: the per-site config, the connectors registered on it, and its JWT signing keys.
Tableau WIF admin REST API endpoints are available in REST API version 3.30 and later (Tableau Server release 26.3). All methods require the WIF feature to be enabled on the site AND the caller to be a Site Administrator; the server returns HTTP 403 (ServerResponseError) when either is missing, including on get(). Once WIF is available on the site, get() works immediately (returns a shell with enabled=False until the admin calls enable()). update() and the four connector methods return HTTP 404 until enable() has run; delete() on a never-enabled site is a no-op. create_key() is not gated by enable() and will create an orphan key against the per-site key limit if called first; activate_key, deactivate_key, and delete_key return HTTP 404 only if the key id does not exist on the site.
The four key-management methods (create_key, activate_key, deactivate_key, delete_key) are bound to the server’s NO_ACCESS scope, which only rejects OAuth-scope-restricted sessions (for example, a connected-app JWT session) — the server returns HTTP 401, surfaced by TSC as FailedSignInError. Password sessions and personal-access-token (PAT) sessions do not carry scopes and are accepted. The config and connector methods additionally accept the tableau:connectivity_auth_federation:* OAuth scopes.
AuthFederationItem class
The AuthFederationItem represents the per-site WIF admin configuration on Tableau Server or Tableau Cloud.
Attributes
| Name |
Description |
enabled |
bool. Whether WIF is enabled on the site. False on a shell returned from get() for a never-enabled site. |
issuer_url |
str or None. The server-generated issuer URL for JWTs minted by this site. Read-only — the server derives it from the site identifier. |
active_key_id |
str or None. The kid of the currently active signing key, or None if the site has no active key. |
token_lifetime_seconds |
int or None. The JWT lifetime in seconds. The server default is 7200. |
connectors |
list[AuthFederationConnectorItem]. The connectors registered on the site. Populated by get(); list_connectors() returns the same list directly. |
Source file: models/auth_federation_item.py
AuthFederationConnectorItem class
The AuthFederationConnectorItem represents a single connector registered on a WIF-enabled site. Each connector binds a Tableau connection class to a cloud-provider audience; the per-site signing key mints JWTs with that audience as the aud claim.
Attributes
| Name |
Description |
luid |
str or None. The server-assigned identifier for the connector. Populated by create_connector() and by response-parsing of get_connector() / list_connectors(). |
connector_class |
str or None. The Tableau connection class the connector is bound to (for example, "bigquery" or "snowflake"). Must equal the exact lowercase connection class — what ConnectionItem.connection_type reports for the connector. Class names are case-sensitive. |
audience |
str or None. The cloud-provider audience that scopes the minted JWT. For GCP, this is the full Workload Identity Pool provider resource name. |
Example
import tableauserverclient as TSC
new_connector = TSC.AuthFederationConnectorItem()
new_connector.connector_class = 'bigquery'
new_connector.audience = (
'//iam.googleapis.com/projects/123456789/locations/global/'
'workloadIdentityPools/tableau-pool/providers/tableau-provider'
)
Source file: models/auth_federation_item.py
AuthFederationKeyItem class
The AuthFederationKeyItem represents the public JWK metadata for a signing key on a WIF-enabled site. The private key is never exposed by the REST API.
Attributes
| Name |
Description |
kid |
str or None. The key identifier. |
kty |
str or None. JWK key type (for example, "RSA"). |
alg |
str or None. JWK signing algorithm (for example, "RS256"). |
use |
str or None. JWK key use (for example, "sig"). |
n |
str or None. The RSA public modulus, base64url-encoded. |
e |
str or None. The RSA public exponent, base64url-encoded. |
Source file: models/auth_federation_item.py
Auth Federation methods
The Tableau Server Client provides twelve methods for interacting with the WIF admin resources on a site: four for the per-site config, four for connectors, and four for signing keys.
Each id-taking method (get_connector, delete_connector, activate_key, deactivate_key, delete_key) validates its target client-side before any HTTP call; None, empty strings, and non-UUID-shaped targets raise ValueError, preventing path injection.
Source file: server/endpoint/auth_federation_endpoint.py
auth_federation.get
Returns the WIF admin configuration for the currently authenticated site. A site that has never enabled WIF returns a default AuthFederationItem with enabled=False rather than raising an exception.
Version
Available with REST API 3.30 and later (Tableau Server release 26.3).
Returns
Returns an AuthFederationItem.
Example
with server.auth.sign_in(tableau_auth):
config = server.auth_federation.get()
print(f"WIF enabled: {config.enabled}, active key: {config.active_key_id}")
auth_federation.enable
auth_federation.enable(token_lifetime_seconds=None)
Enables WIF on the currently authenticated site. Idempotent: calling enable on an already-enabled site returns the current config without changing it.
On first enable (not on subsequent idempotent calls), the server auto-generates one active signing key and populates active_key_id on the returned item, so a caller does not need to immediately create_key and activate_key.
Version
Available with REST API 3.30 and later.
Parameters
| Name |
Description |
token_lifetime_seconds |
(Optional) The JWT lifetime in seconds. None leaves the server default (7200 seconds) in place, or on an already-enabled site keeps whatever lifetime is currently configured. |
Returns
Returns an AuthFederationItem with the current WIF admin config.
Example
with server.auth.sign_in(tableau_auth):
config = server.auth_federation.enable(token_lifetime_seconds=3600)
print(f"Active signing key auto-created: {config.active_key_id}")
auth_federation.update
auth_federation.update(token_lifetime_seconds)
Merge-patches the mutable fields of the WIF admin config. Only token_lifetime_seconds is mutable; enabled, issuer_url, active_key_id, and connectors are not. Use enable() or delete() to change WIF state, and the connector / key endpoints to manage those resources. Returns HTTP 404 if WIF has never been enabled on the site.
Version
Available with REST API 3.30 and later.
Parameters
| Name |
Description |
token_lifetime_seconds |
New JWT lifetime in seconds. Required — token_lifetime_seconds is the only mutable field, so a no-arg call would not be a meaningful operation. |
Returns
Returns the updated AuthFederationItem.
Example
with server.auth.sign_in(tableau_auth):
config = server.auth_federation.update(token_lifetime_seconds=7200)
auth_federation.delete
Deletes the WIF admin config, every signing key, and every connector on the site. Any datasource or workbook connections that reference a WIF connector will no longer be able to authenticate until WIF is re-enabled; the removed connectors and keys are not restored by a subsequent enable(). A delete() call on a site that has never enabled WIF is a no-op.
Version
Available with REST API 3.30 and later.
Example
with server.auth.sign_in(tableau_auth):
server.auth_federation.delete()
auth_federation.create_connector
auth_federation.create_connector(connector)
Registers a new WIF connector on the site. The server assigns the connector LUID. Fails with HTTP 409 (ServerResponseError) if a connector with the same connector_class already exists on the site.
Version
Available with REST API 3.30 and later.
Parameters
| Name |
Description |
connector |
An AuthFederationConnectorItem with connector_class and audience set. Both fields are validated client-side; a missing field raises ValueError. connector_class must equal the exact lowercase Tableau connection class — what ConnectionItem.connection_type reports for the connector (for example, "bigquery", "snowflake"). |
Returns
Returns the created AuthFederationConnectorItem, with the server-assigned luid populated.
Example
new_connector = TSC.AuthFederationConnectorItem()
new_connector.connector_class = 'bigquery'
new_connector.audience = (
'//iam.googleapis.com/projects/123456789/locations/global/'
'workloadIdentityPools/tableau-pool/providers/tableau-provider'
)
with server.auth.sign_in(tableau_auth):
created = server.auth_federation.create_connector(new_connector)
print(f"Connector LUID: {created.luid}")
auth_federation.list_connectors
auth_federation.list_connectors()
Returns every WIF connector registered on the site. Returns an empty list if WIF is enabled but has no connectors. If WIF has not been enabled on the site, the server returns HTTP 404 (ServerResponseError) — call enable() first.
Version
Available with REST API 3.30 and later.
Returns
Returns list[AuthFederationConnectorItem].
Example
with server.auth.sign_in(tableau_auth):
connectors = server.auth_federation.list_connectors()
for c in connectors:
print(f"{c.connector_class} -> {c.audience}")
auth_federation.get_connector
auth_federation.get_connector(connector)
Returns a single WIF connector by LUID.
Version
Available with REST API 3.30 and later.
Parameters
| Name |
Description |
connector |
The connector LUID (str), or an AuthFederationConnectorItem whose luid is set. |
Exceptions
| Error |
Description |
Invalid UUID |
Raises ValueError if the target is not a well-formed UUID (including None, empty, or path-like strings). |
Returns
Returns an AuthFederationConnectorItem.
auth_federation.delete_connector
auth_federation.delete_connector(connector)
Deletes a WIF connector by LUID. Idempotent on an unknown but well-formed LUID (the server returns 204 even if no such connector exists), but only when WIF is enabled on the site; otherwise the server returns a WIF-not-enabled error. Client-side UUID validation rejects a malformed id before any HTTP call.
Existing site connections that reference the removed connector are orphaned, not cascade-deleted.
Version
Available with REST API 3.30 and later.
Parameters
| Name |
Description |
connector |
The connector LUID (str), or an AuthFederationConnectorItem whose luid is set. |
Exceptions
| Error |
Description |
Invalid UUID |
Raises ValueError if the target is not a well-formed UUID. |
auth_federation.create_key
auth_federation.create_key()
Generates a new WIF signing key. Keys are created in the inactive state; use activate_key to promote one to the site’s active signing key. Fails with HTTP 400 (ServerResponseError) if the site is already at the maximum number of keys.
Version
Available with REST API 3.30 and later.
Returns
Returns an AuthFederationKeyItem with the created key’s JWK metadata (kid, kty, alg, use, n, e). The private key is never exposed by the REST API.
Example
with server.auth.sign_in(tableau_auth):
key = server.auth_federation.create_key()
print(f"New key id: {key.kid}")
auth_federation.activate_key
auth_federation.activate_key(key)
Promotes the given key to the site’s active signing key. Atomic: deactivates whichever key was previously active in the same operation, so the site is never without an active signing key during rotation.
Version
Available with REST API 3.30 and later.
Parameters
| Name |
Description |
key |
The key id (kid), or an AuthFederationKeyItem whose kid is set. |
Exceptions
| Error |
Description |
Invalid UUID |
Raises ValueError if the target is not a well-formed UUID. |
auth_federation.deactivate_key
auth_federation.deactivate_key(key)
Deactivates the given key. A deactivated key stays on the site (and in the public JWKS) so already-issued JWTs can still be verified during their validity window, but no new JWTs will be signed with it. Calling deactivate_key on the active key without first activating a replacement leaves the site unable to mint WIF tokens until a replacement is activated.
Version
Available with REST API 3.30 and later.
Parameters
| Name |
Description |
key |
The key id (kid), or an AuthFederationKeyItem whose kid is set. |
Exceptions
| Error |
Description |
Invalid UUID |
Raises ValueError if the target is not a well-formed UUID. |
auth_federation.delete_key
auth_federation.delete_key(key)
Deletes a WIF signing key. Fails with HTTP 400 if the key is currently active.
Unlike deactivate_key, which keeps the (now-inactive) key published in the site’s JWKS so already-issued JWTs can still be verified, delete_key removes the key from the JWKS entirely — any verifier that fetches the key set afterwards will reject still-unexpired tokens signed with it. For a safe rotation, keep the old key deactivated-but-published until every JWT it signed has expired (upper bound: the site’s current token_lifetime_seconds, default 7200 s / 2 h), and only then delete it.
Version
Available with REST API 3.30 and later.
Parameters
| Name |
Description |
key |
The key id (kid), or an AuthFederationKeyItem whose kid is set. |
Exceptions
| Error |
Description |
Invalid UUID |
Raises ValueError if the target is not a well-formed UUID. |
Connections
The connections for Tableau Server data sources and workbooks are represented by a ConnectionItem class. You can call data source and workbook methods to query or update the connection information. The ConnectionCredentials class represents the connection information you can update.
ConnectionItem class
The ConnectionItem class corresponds to workbook and data source connections.
In the Tableau Server REST API, there are separate endpoints to query and update workbook and data source connections.
Attributes
| Name |
Description |
datasource_id |
The identifier of the data source. |
datasource_name |
The name of the data source. |
id |
The identifier of the connection. |
connection_type |
The type of connection. |
username |
The username for the connection (see ConnectionCredentials). |
password |
The password used for the connection (see ConnectionCredentials). |
embed_password |
(Boolean) Determines whether to embed the password (True) for the workbook or data source connection or not (False) (see ConnectionCredentials). |
server_address |
The server address for the connection (host name for the Tableau Server). |
server_port |
The port used for the connection. |
connection_credentials |
The Connection Credentials object containing authentication details for the connection. Replaces username/password/embed_password when publishing a flow, document or workbook file in the request body. |
workgroup_auth_mode |
(Optional) The Workload Identity Federation (WIF) auth mode for the connection. Set to one of the values on the ConnectionItem.WorkgroupAuthMode nested value set: WIF ("workload-identity-federation", e.g. Snowflake direct WIF) or WIF_IMPERSONATION ("workload-identity-federation-impersonation", e.g. Google BigQuery impersonation WIF). Requires REST API 3.30+ (Tableau Server release 26.3) with WIF configured on the site. Older servers silently ignore the attribute. |
auth_federation_service_account |
(Optional) The service account email the server impersonates for WIF. Set this only together with workgroup_auth_mode = WorkgroupAuthMode.WIF_IMPERSONATION; the server rejects a service account alongside the direct WIF mode. |
Source file: models/connection_item.py
ConnectionCredentials class
ConnectionCredentials(name, password, embed=True, oauth=False)
The ConnectionCredentials class is used for workbook and data source publish requests.
Attributes
| Attribute |
Description |
name |
The username for the connection. |
embed |
(Boolean) Determines whether to embed the password (True) for the workbook or data source connection or not (False). |
password |
The password used for the connection. |
ouath |
(Boolean) Specifies whether OAuth is used for the data source of workbook connection. For more information, see OAuth Connections. |
Source file: models/connection_credentials.py
Custom Views
Using the TSC library, you can get information about custom views, update custom views, delete custom views, and export custom views as images, PDFs, or CSV files.
The custom view resources for Tableau Server are defined in the CustomViewItem class. The class corresponds to the custom view resources you can access using the Tableau Server REST API. The custom view methods are based upon the endpoints for custom views in the REST API and operate on the CustomViewItem class.
CustomViewItem class
CustomViewItem(id=None, name=None)
The CustomViewItem class contains the members or attributes for the custom view resources on Tableau Server. The CustomViewItem class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
Source file: models/custom_view_item.py
Attributes
| Name |
Description |
content_url |
The content URL of the custom view. |
created_at |
The date and time the custom view was created. |
csv |
The CSV data of the custom view. You must first call the custom_views.populate_csv method to access the CSV data. |
id |
The identifier of the custom view item. |
image |
The image of the custom view. You must first call the custom_views.populate_image method to access the image. |
name |
The name of the custom view. |
owner |
The owner of the custom view (UserItem). |
pdf |
The PDF of the custom view. You must first call the custom_views.populate_pdf method to access the PDF content. |
shared |
Whether the custom view is shared (boolean). |
updated_at |
The date and time the custom view was last updated. |
view |
The view (ViewItem) the custom view belongs to. |
workbook |
The workbook (WorkbookItem) the custom view belongs to. |
Custom Views methods
The Tableau Server Client provides methods for interacting with custom view resources, or endpoints. These methods correspond to the endpoints for custom views in the Tableau Server REST API.
Source file: server/endpoint/custom_views_endpoint.py
custom_views.get
custom_views.get(req_options=None)
Returns the list of custom views on a site.
The returned list can be adjusted with filter parameters as follows:
- If the request has no filter parameters: Administrators will see all custom views. Other users will see only custom views that they own.
- If the filter parameters include ownerId: Users will see only custom views that they own.
- If the filter parameters include viewId or workbookId, and don’t include ownerId: Users will see those custom views for which they have Write and WebAuthoring permissions.
- If site user visibility is not set to Limited, the Users will see those custom views that are “public”, meaning the value of their shared attribute is true.
REST API: List Custom Views
Version
This endpoint is available with REST API version 3.18 and up.
Parameters
| Name |
Description |
req_options |
(Optional) Filtering options for the request. You can filter by view_id, workbook_id, or owner_id. |
Returns
Returns a list of all CustomViewItem objects and a PaginationItem. Use these values to iterate through the results.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('username', 'password')
server = TSC.Server('https://servername')
with server.auth.sign_in(tableau_auth):
all_custom_views, pagination_item = server.custom_views.get()
print([view.name for view in all_custom_views])
See CustomViewItem class
custom_views.get_by_id
custom_views.get_by_id(view_id)
Returns the details of a specific custom view.
REST API: Get Custom View
Version
This endpoint is available with REST API version 3.18 and up.
Parameters
| Name |
Description |
view_id |
The ID of the custom view to retrieve. |
Returns
Returns a single CustomViewItem object.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('username', 'password')
server = TSC.Server('https://servername')
with server.auth.sign_in(tableau_auth):
custom_view = server.custom_views.get_by_id('d79634e1-6063-4ec9-95ff-50acbf609ff5')
print(custom_view.name)
See CustomViewItem class
custom_views.populate_image
custom_views.populate_image(view_item, req_options=None)
Populates the image of the specified custom view.
This method uses the id field to query the image, and populates the image content as the image field.
REST API: Get Custom View Image
Version
This endpoint is available with REST API version 3.18 and up.
Parameters
| Name |
Description |
view_item |
Specifies the custom view to populate. |
req_options |
(Optional) You can pass in request options to specify the image resolution (imageresolution) and the maximum age of the view image cached on the server (maxage). See ImageRequestOptions class for more details. |
Exceptions
| Error |
Description |
Custom View item missing ID |
Raises an error if the ID of the custom view is missing. |
Returns
None. The image is added to the view_item and can be accessed by its image field.
Example
# Sign in, get custom view, etc.
# Populate and save the custom view image as 'custom_view_image.png'
server.custom_views.populate_image(custom_view_item)
with open('./custom_view_image.png', 'wb') as f:
f.write(custom_view_item.image)
See CustomViewItem class
custom_views.populate_pdf
custom_views.populate_pdf(custom_view_item, req_options=None)
Populates the PDF content of the specified custom view.
This method populates a PDF with image(s) of the custom view you specify.
REST API: Get Custom View PDF
Version
This endpoint is available with REST API version 3.23 and up.
Parameters
| Name |
Description |
custom_view_item |
Specifies the custom view to populate. |
req_options |
(Optional) You can pass in request options to specify the page type and orientation of the PDF content, as well as the maximum age of the PDF rendered on the server. See PDFRequestOptions class for more details. |
Exceptions
| Error |
Description |
Custom View item missing ID |
Raises an error if the ID of the custom view is missing. |
Returns
None. The PDF content is added to the custom_view_item and can be accessed by its pdf field.
Example
# Sign in, get custom view, etc.
# Populate and save the custom view pdf as 'custom_view_pdf.pdf'
server.custom_views.populate_pdf(custom_view_item)
with open('./custom_view_pdf.pdf', 'wb') as f:
f.write(custom_view_item.pdf)
See CustomViewItem class
custom_views.populate_csv
custom_views.populate_csv(custom_view_item, req_options=None)
Populates the CSV data of the specified custom view.
This method uses the id field to query the CSV data, and populates the data as the csv field.
REST API: Get Custom View Data
Version
This endpoint is available with REST API version 3.23 and up.
Parameters
| Name |
Description |
custom_view_item |
Specifies the custom view to populate. |
req_options |
(Optional) You can pass in request options to specify the maximum age of the CSV cached on the server. See CSVRequestOptions class for more details. |
Exceptions
| Error |
Description |
Custom View item missing ID |
Raises an error if the ID of the custom view is missing. |
Returns
None. The CSV data is added to the custom_view_item and can be accessed by its csv field.
Example
# Sign in, get custom view, etc.
# Populate and save the CSV data in a file
server.custom_views.populate_csv(custom_view_item)
with open('./custom_view_data.csv', 'wb') as f:
# Perform byte join on the CSV data
f.write(b''.join(custom_view_item.csv))
See CustomViewItem class
custom_views.update
custom_views.update(view_item)
Updates the name, owner, or shared status of a custom view.
REST API: Update Custom View
Version
This endpoint is available with REST API version 3.18 and up.
Parameters
| Name |
Description |
view_item |
The custom view item to update. Must include the id field. You can update the name, owner, or shared attributes. |
Returns
Returns the updated CustomViewItem object.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('username', 'password')
server = TSC.Server('https://servername')
with server.auth.sign_in(tableau_auth):
# Get a custom view
custom_view = server.custom_views.get_by_id('d79634e1-6063-4ec9-95ff-50acbf609ff5')
# Update the name
custom_view.name = 'Updated Custom View Name'
updated_view = server.custom_views.update(custom_view)
print(f"Updated custom view: {updated_view.name}")
See CustomViewItem class
custom_views.delete
custom_views.delete(view_id)
Deletes a single custom view by ID.
REST API: Delete Custom View
Version
This endpoint is available with REST API version 3.19 and up.
Parameters
| Name |
Description |
view_id |
The ID of the custom view to delete. |
Exceptions
| Error |
Description |
ValueError |
Raises an error if the view_id is not provided or is empty. |
Returns
None.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('username', 'password')
server = TSC.Server('https://servername')
with server.auth.sign_in(tableau_auth):
# Get a custom view
custom_view = server.custom_views.get_by_id('d79634e1-6063-4ec9-95ff-50acbf609ff5')
# Delete the custom view
server.custom_views.delete(custom_view.id)
print(f"Custom view '{custom_view.name}' deleted successfully")
Note: This operation cannot be undone. Make sure you have the correct view ID before deleting.
See CustomViewItem class
custom_views.download
custom_views.download(view_item, file)
Downloads the definition of a custom view as JSON to a file path or file object. The downloaded file may contain sensitive information.
Version
This endpoint is available with REST API version 3.21 and up.
Parameters
| Name |
Description |
view_item |
The CustomViewItem to download. |
file |
The file path (str or Path) or writable file object to write the definition to. |
Returns
Returns the file path or file object that the custom view definition was written to.
Example
custom_view = server.custom_views.get_by_id('d79634e1-6063-4ec9-95ff-50acbf609ff5')
server.custom_views.download(custom_view, './my_custom_view.json')
See CustomViewItem class
custom_views.publish
custom_views.publish(view_item, file)
Publishes a custom view to Tableau Server from a JSON definition file previously downloaded with custom_views.download.
Version
This endpoint is available with REST API version 3.21 and up.
Parameters
| Name |
Description |
view_item |
The CustomViewItem describing the custom view to publish. Must have a name set. |
file |
The file path (str or Path) or readable file object containing the definition. |
Exceptions
| Error |
Description |
ValueError |
Raised if file is not a valid file path or file object. |
MissingRequiredFieldError |
Raised if view_item.name is not set when passing a file object. |
Returns
Returns the published CustomViewItem, or None.
Example
new_view = TSC.CustomViewItem(name='My Custom View')
published = server.custom_views.publish(new_view, './my_custom_view.json')
print(published.id)
See CustomViewItem class
custom_views.filter
custom_views.filter(**kwargs)
Returns a list of custom views that match the specified filters. Fields and operators are passed as keyword arguments in the form field_name=value.
Supported fields and operators
| Field |
Operators |
owner_id |
eq |
view_id |
eq |
workbook_id |
eq |
Returns
Returns a QuerySet of CustomViewItem objects.
Example
my_views = server.custom_views.filter(owner_id=user_item.id)
for view in my_views:
print(view.name)
Data Sources
Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project.
The data source resources for Tableau Server are defined in the DatasourceItem class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about the name of the data source, its type, its connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the DatasourceItem class.
DatasourceItem class
DatasourceItem(project_id, name=None)
The DatasourceItem represents the data source resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for data sources. When you create a new DatasourceItem instance, you must specify the project_id that the data source is associated with.
Attributes
| Name |
Description |
ask_data_enablement |
Determines if a data source allows use of Ask Data. The value can be TSC.DatasourceItem.AskDataEnablement.Enabled, TSC.DatasourceItem.AskDataEnablement.Disabled, or TSC.DatasourceItem.AskDataEnablement.SiteDefault. If no setting is specified, it will default to SiteDefault. See REST API Publish Datasource for more information about ask_data_enablement. |
connections |
The list of data connections (ConnectionItem) for the specified data source. You must first call the populate_connections method to access this data. See the ConnectionItem class. |
content_url |
The name of the data source as it would appear in a URL. |
created_at |
The date and time when the data source was created. |
certified |
A Boolean value that indicates whether the data source is certified. |
certification_note |
The optional note that describes the certified data source. |
datasource_type |
The type of data source, for example, sqlserver or excel-direct. |
description |
The description for the data source. |
encrypt_extracts |
A Boolean value to determine if a datasource should be encrypted or not. See Extract and Encryption Methods for more information. |
has_extracts |
A Boolean value that indicates whether the datasource has extracts. |
id |
The identifier for the data source. You need this value to query a specific data source or to delete a data source with the get_by_id and delete methods. |
name |
The name of the data source. If not specified, the name of the published data source file is used. |
owner_id |
The identifier of the owner of the data source. |
project_id |
The identifier of the project associated with the data source. You must provide this identifier when you create an instance of a DatasourceItem. |
project_name |
The name of the project associated with the data source. |
tags |
The tags (list of strings) that have been added to the data source. |
updated_at |
The date and time when the data source was last updated. |
use_remote_query_agent |
A Boolean value that indicates whether to allow or disallow your Tableau Cloud site to use Tableau Bridge clients. Bridge allows you to maintain data sources with live connections to supported on-premises data sources. See Configure and Manage the Bridge Client Pool for more information. |
webpage_url |
The url of the datasource as displayed in browsers. |
Example
import tableauserverclient as TSC
# Create new datasource_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39'
new_datasource = TSC.DatasourceItem('3a8b6148-493c-11e6-a621-6f3499394a39')
Source file: models/datasource_item.py
Datasources methods
The Tableau Server Client provides several methods for interacting with data source resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
Source file: server/endpoint/datasources_endpoint.py
datasources.delete
datasources.delete(datasource_id)
Removes the specified data source from Tableau Server.
REST API: Delete Data Source
Parameters
| Name |
Description |
datasource_id |
The identifier (id) for the DatasourceItem that you want to delete from the server. |
Exceptions
| Error |
Description |
Datasource ID undefined |
Raises an exception if a valid datasource_id is not provided. |
REST API: Delete Datasource
datasources.download
datasources.download(datasource_id, filepath=None, include_extract=True, no_extract=None)
Downloads the specified data source in .tdsx or .hyper format.
REST API: Download Datasource
Parameters
| Name |
Description |
datasource_id |
The identifier (id) for the DatasourceItem that you want to download from the server. |
filepath |
(Optional) Downloads the file to the location you specify. If no location is specified (the default is Filepath=None), the file is downloaded to the current working directory. |
include_extract |
(Optional) Specifies whether to download the file with the extract. The default is to include the extract, if present (include_extract=True). When the data source has an extract, if you set the parameter include_extract=False, the extract is not included. You can use this parameter to improve performance if you are downloading data sources that have large extracts. Available starting with Tableau Server REST API version 2.5. |
no_extract |
(Deprecated) Use include_extract instead. The default value is to ignore this parameter (no_extract=None). If you set the parameter to no_extract=True, the download will not include an extract (if there is one). If set to no_extract=False, the download will include the extract (if there is one). Available starting with Tableau Server REST API version 2.5. |
Exceptions
| Error |
Description |
Datasource ID undefined |
Raises an exception if a valid datasource_id is not provided. |
Returns
The file path to the downloaded data source. The data source is downloaded in .tdsx or .hyper format.
Example
file_path = server.datasources.download('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
print("\nDownloaded the file to {0}.".format(file_path))
datasources.get
datasources.get(req_options=None)
Returns all the data sources for the site.
To get the connection information for each data source, you must first populate the DatasourceItem with connection information using the populate_connections(datasource_item) method. For more information, see Populate Connections and Views
REST API: Query Datasources
Parameters
| Name |
Description |
req_options |
(Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific data source, you could specify the name of the project or its id. |
Returns
Returns a list of DatasourceItem objects and a PaginationItem object. Use these values to iterate through the results.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
all_datasources, pagination_item = server.datasources.get()
print("\nThere are {} datasources on site: ".format(pagination_item.total_available))
print([datasource.name for datasource in all_datasources])
datasources.get_by_id
datasources.get_by_id(datasource_id)
Returns the specified data source item.
REST API: Query Datasource
Parameters
| Name |
Description |
datasource_id |
The datasource_id specifies the data source to query. |
Exceptions
| Error |
Description |
Datasource ID undefined |
Raises an exception if a valid datasource_id is not provided. |
Returns
The DatasourceItem. See DatasourceItem class
Example
datasource = server.datasources.get_by_id('59a57c0f-3905-4022-9e87-424fb05e9c0e')
print(datasource.name)
datasources.populate_connections
datasources.populate_connections(datasource_item)
Populates the connections for the specified data source.
This method retrieves the connection information for the specified data source. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the connection information is not included. Use this method to retrieve the connections. The method adds the list of data connections to the data source item (datasource_item.connections). This is a list of ConnectionItem objects.
REST API: Query Datasource Connections
Parameters
| Name |
Description |
datasource_item |
The datasource_item specifies the data source to populate with connection information. |
Exceptions
| Error |
Description |
Datasource item missing ID. Datasource must be retrieved from server first. |
Raises an error if the datasource_item is unspecified. |
Returns
None. A list of ConnectionItem objects are added to the data source (datasource_item.connections).
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://SERVERURL')
#
...
# get the data source
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
# get the connection information
server.datasources.populate_connections(datasource)
# print the information about the first connection item
connection = datasource.connections[0]
print(connection.connection_type)
print(connection.id)
print(connection.server_address)
...
datasources.publish
datasources.publish(datasource_item, file, mode, connection_credentials=None, as_job=False)
Publishes a data source to a server, or appends data to an existing data source.
This method checks the size of the data source and automatically determines whether the publish the data source in multiple parts or in one operation.
REST API: Publish Datasource
Parameters
| Name |
Description |
datasource_item |
The datasource_item specifies the new data source you are adding, or the data source you are appending to. If you are adding a new data source, you need to create a new datasource_item with a project_id of an existing project. The name of the data source will be the name of the file, unless you also specify a name for the new data source when you create the instance. See DatasourceItem. |
file |
The file path or file object of the data source to publish. |
mode |
Specifies whether you are publishing a new data source (CreateNew), overwriting an existing data source (Overwrite), or appending data to a data source (Append). If you are appending to a data source, the data source on the server and the data source you are publishing must be be extracts (.tde files) and they must share the same schema. You can also use the publish mode attributes, for example: TSC.Server.PublishMode.Overwrite. |
connection_credentials |
(Optional) The credentials required to connect to the data source. The ConnectionCredentials object contains the authentication information for the data source (user name and password, and whether the credentials are embedded or OAuth is used). |
as_job |
(Optional) If this value is set to True, the publish operation will be asynchronous and return a JobItem. |
Exceptions
| Error |
Description |
File path does not lead to an existing file. |
Raises an error of the file path is incorrect or if the file is missing. |
Invalid mode defined. |
Raises an error if the publish mode is not one of the defined options. |
Only .tds, tdsx, .tde, or .hyper files can be published as datasources. |
Raises an error if the type of file specified is not supported. |
Returns
The DatasourceItem for the data source that was added or appended to.
Example
import tableauserverclient as TSC
server = TSC.Server('https://SERVERURL')
...
project_id = '3a8b6148-493c-11e6-a621-6f3499394a39'
file_path = r'C:\temp\WorldIndicators.tde'
# Use the project id to create new datsource_item
new_datasource = TSC.DatasourceItem(project_id)
# publish data source (specified in file_path)
new_datasource = server.datasources.publish(
new_datasource, file_path, 'CreateNew')
...
datasources.refresh
datasources.refresh(datasource_item)
Refreshes the data of the specified extract.
REST API: Update Data Source Now
Parameters
| Name |
Description |
datasource_item |
The datasource_item specifies the data source to update. |
Exceptions
| Error |
Description |
Datasource item missing ID. Datasource must be retrieved from server first. |
Raises an error if the datasource_item is unspecified. Use the Datasources.get() method to retrieve that identifies for the data sources on the server. |
Returns
A refreshed JobItem.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://SERVERURL')
# sign in ...
# get the data source item to update
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
# call the refresh method with the data source item
refreshed_datasource = server.datasources.refresh(datasource)
datasources.update
datasource.update(datasource_item)
Updates the specified data source.
REST API: Update Data Source
Parameters
| Name |
Description |
datasource_item |
The datasource_item specifies the data source to update. |
Exceptions
| Error |
Description |
Datasource item missing ID. Datasource must be retrieved from server first. |
Raises an error if the datasource_item is unspecified. Use the Datasources.get() method to retrieve that identifies for the data sources on the server. |
Returns
An updated DatasourceItem.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://SERVERURL')
# sign in ...
# get the data source item to update
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
# do some updating
datasource.owner_id = 'New Owner ID'
# call the update method with the data source item
updated_datasource = server.datasources.update(datasource)
datasources.update_connection
datasources.update_connection(datasource_item, connection_item)
Updates the server address, port, username, or password for the specified data source connection.
REST API: Update Datasource Connection
Parameters
| Name |
Description |
datasource_item |
The datasource_item specifies the data source to update. |
connection_item |
The connection_item that has the information you want to update. |
Returns
An updated ConnectionItem for the data source.
Example
See the update_connection.py sample in the Samples directory.
datasources.update_hyper_data
datasources.update_hyper_data(datasource_or_connection_item, *, request_id, actions, payload=None)
Updates the data contained within a published live-to-Hyper datasource.
REST API: Update Data in Hyper Data Source
Version
This endpoint is available with REST API version 3.13 and up.
Parameters
| Name |
Description |
datasource_or_connection_item |
Either a DataSourceItem or a ConnectionItem. If the datasource only contains a single connection, the DataSourceItem is sufficient to identify which data should be updated. Otherwise, for datasources with multiple connections, a ConnectionItem must be provided. |
request_id |
User supplied arbitrary string to identify the request. A request identified with the same key will only be executed once, even if additional requests using the key are made, for instance, due to retries when facing network issues. |
actions |
a list of actions (insert, update, delete, …) specifying how to modify the data within the published datasource |
payload |
an (optional) Hyper file containing tuples to be inserted/deleted or other payload data used by the actions. |
For more information on the actions, see the REST API docs on “Action batch description”.
To create a payload Hyper file, you can use Hyper API or pantab.
Returns
A JobItem for the update job on the server. Upon completion of this job, the data was updated.
Example
See the update_datasource_data.py sample in the Samples directory.
datasources.create_extract
datasources.create_extract(datasource_item, encrypt=False)
Creates an extract for the specified data source.
REST API: Create an Extract for a Data Source
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to create an extract for. |
encrypt |
(Optional) Specifies whether to encrypt the extract. The default is False. |
Returns
Returns a JobItem for the extract creation job.
Version
Version 3.5 and later. See REST API versions.
Example
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
job = server.datasources.create_extract(datasource, encrypt=True)
server.jobs.wait_for_job(job)
datasources.delete_extract
datasources.delete_extract(datasource_item)
Removes the extract from the specified data source.
REST API: Delete the Extract from a Data Source
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to remove the extract from. |
Version
Version 3.5 and later. See REST API versions.
Example
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.datasources.delete_extract(datasource)
datasources.populate_permissions
datasources.populate_permissions(datasource_item)
Populates the permissions for the specified data source.
REST API: List Data Source Permissions
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to populate with permissions. |
Version
Version 2.0 and later. See REST API versions.
Example
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.datasources.populate_permissions(datasource)
for permission in datasource.permissions:
print(permission.grantee_id, permission.capabilities)
datasources.update_permissions
datasources.update_permissions(datasource_item, permission_item)
Adds or updates permissions for the specified data source.
REST API: Replace Content Permissions
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to update permissions for. |
permission_item |
A list of PermissionsRule objects representing the permissions to add or update. |
Version
Version 2.0 and later. See REST API versions.
datasources.delete_permission
datasources.delete_permission(datasource_item, capability_item)
Removes a permission from the specified data source.
REST API: Delete Data Source Permission
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to remove the permission from. |
capability_item |
The PermissionsRule object representing the permission to remove. |
Version
Version 2.0 and later. See REST API versions.
datasources.populate_dqw
datasources.populate_dqw(datasource_item)
Populates the data quality warnings for the specified data source.
REST API: Query Data Quality Warning by Content
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to populate with data quality warnings. |
Version
Version 3.5 and later. See REST API versions.
Example
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.datasources.populate_dqw(datasource)
for dqw in datasource.dqws:
print(dqw.message)
datasources.add_dqw
datasources.add_dqw(datasource_item, warning)
Adds a data quality warning to the specified data source.
REST API: Add Data Quality Warning
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to add the data quality warning to. |
warning |
The DQWItem object representing the data quality warning to add. |
Version
Version 3.5 and later. See REST API versions.
datasources.update_dqw
datasources.update_dqw(datasource_item, warning)
Updates a data quality warning on the specified data source.
REST API: Update Data Quality Warning
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to update the data quality warning on. |
warning |
The DQWItem object representing the updated data quality warning. |
Version
Version 3.5 and later. See REST API versions.
datasources.delete_dqw
datasources.delete_dqw(datasource_item)
Removes all data quality warnings from the specified data source.
REST API: Delete Quality Warning Triggers by Content
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to remove data quality warnings from. |
Version
Version 3.5 and later. See REST API versions.
datasources.populate_revisions
datasources.populate_revisions(datasource_item)
Populates the revision history for the specified data source.
REST API: Get Data Source Revisions
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to populate with revision history. |
Exceptions
| Error |
Description |
Datasource item missing ID. Datasource must be retrieved from server first. |
Raises an exception if the datasource_item does not have an id. |
Version
Version 2.3 and later. See REST API versions.
Example
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.datasources.populate_revisions(datasource)
for revision in datasource.revisions:
print(revision.revision_number, revision.created_at)
datasources.download_revision
datasources.download_revision(datasource_id, revision_number, filepath=None, include_extract=True)
Downloads a specific revision of the specified data source.
REST API: Download Data Source Revision
Parameters
| Name |
Description |
datasource_id |
The identifier (id) for the DatasourceItem. |
revision_number |
The revision number to download. Pass None to download the current (latest) revision. |
filepath |
(Optional) Downloads the file to the location you specify. If no location is specified (the default is filepath=None), the file is downloaded to the current working directory. |
include_extract |
(Optional) Specifies whether to download the file with the extract. The default is True. |
Exceptions
| Error |
Description |
Datasource ID undefined |
Raises an exception if a valid datasource_id is not provided. |
Returns
The file path to the downloaded data source revision.
Version
Version 2.3 and later. See REST API versions.
Example
file_path = server.datasources.download_revision(
'1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b',
revision_number='2'
)
print("\nDownloaded revision to {0}.".format(file_path))
datasources.delete_revision
datasources.delete_revision(datasource_id, revision_number)
Removes a specific revision of the specified data source from Tableau Server.
REST API: Remove Data Source Revision
Parameters
| Name |
Description |
datasource_id |
The identifier (id) for the DatasourceItem. |
revision_number |
The revision number to delete. |
Version
Version 2.3 and later. See REST API versions.
Example
server.datasources.delete_revision('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b', '2')
datasources.schedule_extract_refresh
datasources.schedule_extract_refresh(schedule_id, item)
Convenience method to add a data source to an existing extract refresh schedule.
REST API: Add Data Source to Server Schedule
Parameters
| Name |
Description |
schedule_id |
The identifier of the schedule to add the data source to. |
item |
The DatasourceItem to add to the schedule. |
Returns
Returns a list of AddResponse objects.
Version
Version 2.8 and later. See REST API versions.
Example
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
result = server.datasources.schedule_extract_refresh('schedule-id-here', datasource)
datasources.update_connection
datasources.update_connection(datasource_item, connection_item)
Updates the server address, port, username, or password for the specified data source connection.
REST API: Update Data Source Connection
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem to update. |
connection_item |
The ConnectionItem containing the updated connection details. |
Returns
Returns the updated ConnectionItem, or None if no connection was returned.
Example
server.datasources.populate_connections(datasource_item)
conn = datasource_item.connections[0]
conn.username = 'newuser'
updated_conn = server.datasources.update_connection(datasource_item, conn)
How-to: convert an existing connection to Snowflake keypair auth
As of REST API v3.27, an existing connection can be flipped from username/password to Snowflake keypair authentication in place. First save the private key on the site under Site Settings -> Saved Credentials for Data Sources (keyed on server address + username); the update call only records the auth type and username, it does not carry the key. Then:
server.datasources.populate_connections(datasource_item)
conn = next(c for c in datasource_item.connections if c.connection_type == 'snowflake')
conn.auth_type = 'auth-keypair'
conn.username = 'my_snowflake_user'
conn.embed_password = True
server.datasources.update_connection(datasource_item, conn)
See samples/update_connection_auth.py for a runnable end-to-end example, and the REST API authenticationType reference for the full list of supported values.
How-to: convert an existing connection to Workload Identity Federation (WIF)
As of REST API v3.30 (Tableau Server release 26.3), an existing connection on a WIF-configured site can be flipped to WIF authentication in place. Set workgroup_auth_mode on the ConnectionItem to one of the values on the ConnectionItem.WorkgroupAuthMode nested value set; for the impersonation mode, also set auth_federation_service_account to the service account email. The server derives the stored auth type from the mode, so leave auth_type unset or "oauth".
Direct WIF (e.g., Snowflake):
server.datasources.populate_connections(datasource_item)
conn = next(c for c in datasource_item.connections if c.connection_type == 'snowflake')
conn.workgroup_auth_mode = TSC.ConnectionItem.WorkgroupAuthMode.WIF
server.datasources.update_connection(datasource_item, conn)
Impersonation WIF (e.g., Google BigQuery):
server.datasources.populate_connections(datasource_item)
conn = next(c for c in datasource_item.connections if c.connection_type == 'googlebigquery')
conn.workgroup_auth_mode = TSC.ConnectionItem.WorkgroupAuthMode.WIF_IMPERSONATION
conn.auth_federation_service_account = '[email protected]'
server.datasources.update_connection(datasource_item, conn)
Usage rules the server enforces:
- Resend
workgroup_auth_mode on every subsequent update of a WIF connection; omitting it on a later update returns HTTP 400.
- Set
auth_federation_service_account only with WorkgroupAuthMode.WIF_IMPERSONATION. The server rejects a service account alongside the direct WIF mode.
- The server does not echo
workgroupAuthMode or authFederationServiceAccount on connections-GET responses today, so ConnectionItem.workgroup_auth_mode and ConnectionItem.auth_federation_service_account parsed from a response will typically be None even when the connection is WIF-configured.
datasources.update_connections
datasources.update_connections(datasource_item, connection_luids, authentication_type, username=None, password=None, embed_password=None, workgroup_auth_mode=None, auth_federation_service_account=None)
Bulk updates one or more datasource connections by LUID.
REST API: Update Data Source Connections
Version
This endpoint is available with REST API version 3.26 and up. The workgroup_auth_mode and auth_federation_service_account parameters require REST API 3.30+ (Tableau Server release 26.3).
Parameters
| Name |
Description |
datasource_item |
The DatasourceItem containing the connections to update. |
connection_luids |
An iterable of connection LUIDs (strings) to update. |
authentication_type |
The authentication type to use (e.g., 'auth-keypair'). Leave unset or "oauth" when sending workgroup_auth_mode; the server derives the stored auth type from the WIF mode. |
username |
(Optional) The username to set. |
password |
(Optional) The password or secret to set. |
embed_password |
(Optional) Whether to embed the password. |
workgroup_auth_mode |
(Optional) WIF auth mode to apply to every LUID in the request. One of ConnectionItem.WorkgroupAuthMode.WIF or ConnectionItem.WorkgroupAuthMode.WIF_IMPERSONATION. Requires REST API 3.30+. |
auth_federation_service_account |
(Optional) Service account email to apply to every LUID. Set only together with WIF_IMPERSONATION. |
Returns
Returns a list of updated ConnectionItem objects.
Example
server.datasources.populate_connections(datasource_item)
luids = [conn.id for conn in datasource_item.connections]
updated = server.datasources.update_connections(datasource_item, luids, 'auth-keypair', username='myuser', password='mysecret')
Example — flip connections to WIF (impersonation):
server.datasources.populate_connections(datasource_item)
luids = [conn.id for conn in datasource_item.connections if conn.connection_type == 'googlebigquery']
updated = server.datasources.update_connections(
datasource_item, luids,
authentication_type='oauth',
workgroup_auth_mode=TSC.ConnectionItem.WorkgroupAuthMode.WIF_IMPERSONATION,
auth_federation_service_account='[email protected]',
)
datasources.update_hyper_data
datasources.update_hyper_data(datasource_or_connection_item, *, request_id, actions, payload=None)
Incrementally updates data (insert, update, upsert, replace, or delete) in a published datasource from a live-to-Hyper connection.
For all connections to Parquet files and for datasources with a single connection, you can pass a DatasourceItem. For datasources with multiple connections, pass a ConnectionItem to target the specific connection.
REST API: Update Data in Hyper Data Source
Parameters
| Name |
Description |
datasource_or_connection_item |
A DatasourceItem, ConnectionItem, or datasource ID string. Use a ConnectionItem when the datasource has multiple connections. |
request_id |
A user-supplied string to uniquely identify the request. Duplicate requests with the same key are executed only once. |
actions |
A sequence of action mappings (insert, update, delete, etc.) specifying how to modify the data. See the REST API documentation for action format. |
payload |
(Optional) Path to a Hyper file containing tuple data for the actions. |
Returns
Returns a JobItem for the running job on the server.
Example
actions = [{"action": "insert", "source-table": "my_table", "target-table": "my_table"}]
job = server.datasources.update_hyper_data(
datasource_item,
request_id='unique-request-id-001',
actions=actions,
payload='/path/to/data.hyper'
)
job = server.jobs.wait_for_job(job)
datasources.add_tags
datasources.add_tags(item, tags)
Adds one or more tags to the specified datasource.
REST API: Add Tags to Data Source
Parameters
| Name |
Description |
item |
The DatasourceItem or datasource ID to add tags to. |
tags |
A single tag string or iterable of tag strings to add. |
Returns
Returns a set[str] of the tags added.
Example
server.datasources.add_tags(datasource_item, ['finance', 'quarterly'])
datasources.delete_tags
datasources.delete_tags(item, tags)
Removes one or more tags from the specified datasource.
REST API: Delete Tag from Data Source
Parameters
| Name |
Description |
item |
The DatasourceItem or datasource ID to remove tags from. |
tags |
A single tag string or iterable of tag strings to remove. |
Example
server.datasources.delete_tags(datasource_item, 'finance')
datasources.update_tags
datasources.update_tags(item)
Updates the tags on the server to match the tags on the specified datasource item. Changes to tags must be made on the DatasourceItem.tags attribute before calling this method.
REST API: Delete Tag from Data Source and Add Tags to Data Source
Parameters
| Name |
Description |
item |
The DatasourceItem whose tags to synchronize to the server. |
Example
datasource_item.tags.add('quarterly')
server.datasources.update_tags(datasource_item)
datasources.filter
datasources.filter(**kwargs)
Returns a list of datasources that match the specified filters. Fields and operators are passed as keyword arguments in the form field_name=value or field_name__operator=value.
REST API: Filtering & Sorting Datasources
Supported fields and operators
| Field |
Operators |
authentication_type |
eq, in |
connected_workbook_type |
eq, gt, gte, lt, lte |
connection_to |
eq, in |
connection_type |
eq, in |
content_url |
eq, in |
created_at |
eq, gt, gte, lt, lte |
database_name |
eq, in |
database_user_name |
eq, in |
description |
eq, in |
favorites_total |
eq, gt, gte, lt, lte |
has_alert |
eq |
has_embedded_password |
eq |
has_extracts |
eq |
is_certified |
eq |
is_connectable |
eq |
is_default_port |
eq |
is_hierarchical |
eq |
is_published |
eq |
name |
eq, in |
owner_domain |
eq, in |
owner_email |
eq |
owner_name |
eq, in |
project_name |
eq, in |
server_name |
eq, in |
server_port |
eq |
size |
eq, gt, gte, lt, lte |
table_name |
eq, in |
tags |
eq, in |
type |
eq |
updated_at |
eq, gt, gte, lt, lte |
Returns
Returns a QuerySet of DatasourceItem objects.
Example
certified_ds = server.datasources.filter(is_certified=True, project_name='Finance')
for ds in certified_ds:
print(ds.name)
Favorites
Using the TSC library, you can get, add, and remove favorites for a user. Favorites can be workbooks, views, datasources, flows, projects, or metrics.
The favorites for a user are stored as a dictionary on the UserItem object. The dictionary is keyed by content type ("workbooks", "views", "datasources", "flows", "projects", "metrics", "collections") and each value is a list of the corresponding item objects.
Favorites methods
The Tableau Server Client provides several methods for interacting with favorites. These methods correspond to endpoints in the Tableau Server REST API.
Source file: server/endpoint/favorites_endpoint.py
favorites.get
favorites.get(user_item, req_options=None)
Populates the favorites for the specified user. After calling this method, the favorites are available through user_item.favorites.
REST API: Get Favorites for User
Version
This endpoint is available with REST API version 2.5 and up.
Parameters
| Name |
Description |
user_item |
The UserItem for which to retrieve favorites. |
req_options |
(Optional) Request options such as page size and page number. |
Returns
None. Favorites are populated on user_item.favorites.
Example
server.favorites.get(user_item)
for workbook in user_item.favorites['workbooks']:
print(workbook.name)
favorites.add_favorite
favorites.add_favorite(user_item, content_type, item)
Adds a content item of any supported type to the specified user’s favorites.
REST API: Add Workbook to Favorites
Version
This endpoint is available with REST API version 3.15 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to add the favorite for. |
content_type |
The type of content as a string (e.g., "workbook", "view", "datasource", "flow", "project"). |
item |
The content item to favorite. Must have id and name attributes. |
Returns
Returns the server Response object.
Example
server.favorites.add_favorite(user_item, 'workbook', workbook_item)
favorites.add_favorite_workbook
favorites.add_favorite_workbook(user_item, workbook_item)
Adds a workbook to the specified user’s favorites.
REST API: Add Workbook to Favorites
Version
This endpoint is available with REST API version 2.0 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to add the favorite for. |
workbook_item |
The WorkbookItem to add to favorites. |
Returns
None.
Example
server.favorites.add_favorite_workbook(user_item, workbook_item)
favorites.add_favorite_view
favorites.add_favorite_view(user_item, view_item)
Adds a view to the specified user’s favorites.
REST API: Add View to Favorites
Version
This endpoint is available with REST API version 2.0 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to add the favorite for. |
view_item |
The ViewItem to add to favorites. |
Returns
None.
Example
server.favorites.add_favorite_view(user_item, view_item)
favorites.add_favorite_datasource
favorites.add_favorite_datasource(user_item, datasource_item)
Adds a datasource to the specified user’s favorites.
REST API: Add Data Source to Favorites
Version
This endpoint is available with REST API version 2.3 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to add the favorite for. |
datasource_item |
The DatasourceItem to add to favorites. |
Returns
None.
Example
server.favorites.add_favorite_datasource(user_item, datasource_item)
favorites.add_favorite_project
favorites.add_favorite_project(user_item, project_item)
Adds a project to the specified user’s favorites.
REST API: Add Project to Favorites
Version
This endpoint is available with REST API version 3.1 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to add the favorite for. |
project_item |
The ProjectItem to add to favorites. |
Returns
None.
Example
server.favorites.add_favorite_project(user_item, project_item)
favorites.add_favorite_flow
favorites.add_favorite_flow(user_item, flow_item)
Adds a flow to the specified user’s favorites.
REST API: Add Flow to Favorites
Version
This endpoint is available with REST API version 3.3 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to add the favorite for. |
flow_item |
The FlowItem to add to favorites. |
Returns
None.
Example
server.favorites.add_favorite_flow(user_item, flow_item)
favorites.add_favorite_metric
favorites.add_favorite_metric(user_item, metric_item)
Adds a metric to the specified user’s favorites.
Version
This endpoint is available with REST API version 3.3 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to add the favorite for. |
metric_item |
The MetricItem to add to favorites. |
Returns
None.
Example
server.favorites.add_favorite_metric(user_item, metric_item)
favorites.delete_favorite
favorites.delete_favorite(user_item, content_type, item)
Removes a content item of any supported type from the specified user’s favorites.
Version
This endpoint is available with REST API version 3.15 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to remove the favorite from. |
content_type |
The Resource type of the content (e.g., Resource.Workbook, Resource.View). |
item |
The content item to remove from favorites. Must have an id attribute. |
Returns
None.
Example
server.favorites.delete_favorite(user_item, Resource.Workbook, workbook_item)
favorites.delete_favorite_workbook
favorites.delete_favorite_workbook(user_item, workbook_item)
Removes a workbook from the specified user’s favorites.
REST API: Delete Workbook from Favorites
Version
This endpoint is available with REST API version 2.0 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to remove the favorite from. |
workbook_item |
The WorkbookItem to remove from favorites. |
Returns
None.
Example
server.favorites.delete_favorite_workbook(user_item, workbook_item)
favorites.delete_favorite_view
favorites.delete_favorite_view(user_item, view_item)
Removes a view from the specified user’s favorites.
REST API: Delete View from Favorites
Version
This endpoint is available with REST API version 2.0 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to remove the favorite from. |
view_item |
The ViewItem to remove from favorites. |
Returns
None.
Example
server.favorites.delete_favorite_view(user_item, view_item)
favorites.delete_favorite_datasource
favorites.delete_favorite_datasource(user_item, datasource_item)
Removes a datasource from the specified user’s favorites.
REST API: Delete Data Source from Favorites
Version
This endpoint is available with REST API version 2.3 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to remove the favorite from. |
datasource_item |
The DatasourceItem to remove from favorites. |
Returns
None.
Example
server.favorites.delete_favorite_datasource(user_item, datasource_item)
favorites.delete_favorite_project
favorites.delete_favorite_project(user_item, project_item)
Removes a project from the specified user’s favorites.
REST API: Delete Project from Favorites
Version
This endpoint is available with REST API version 3.1 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to remove the favorite from. |
project_item |
The ProjectItem to remove from favorites. |
Returns
None.
Example
server.favorites.delete_favorite_project(user_item, project_item)
favorites.delete_favorite_flow
favorites.delete_favorite_flow(user_item, flow_item)
Removes a flow from the specified user’s favorites.
REST API: Delete Flow from Favorites
Version
This endpoint is available with REST API version 3.3 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to remove the favorite from. |
flow_item |
The FlowItem to remove from favorites. |
Returns
None.
Example
server.favorites.delete_favorite_flow(user_item, flow_item)
favorites.delete_favorite_metric
favorites.delete_favorite_metric(user_item, metric_item)
Removes a metric from the specified user’s favorites.
Version
This endpoint is available with REST API version 3.15 and up.
Parameters
| Name |
Description |
user_item |
The UserItem to remove the favorite from. |
metric_item |
The MetricItem to remove from favorites. |
Returns
None.
Example
server.favorites.delete_favorite_metric(user_item, metric_item)
Filters
The TSC library provides a Filter class that you can use to filter results returned from the server.
You can use the Filter and RequestOptions classes to filter and sort the following endpoints:
- Users
- Datasources
- Workbooks
- Views
For more information, see Filter and Sort.
Filter class
Filter(field, operator, value)
The Filter class corresponds to the filter expressions in the Tableau REST API.
Attributes
| Name |
Description |
Field |
Defined in the RequestOptions.Field class. |
Operator |
Defined in the RequestOptions.Operator class |
Value |
The value to compare with the specified field and operator. |
Flows
Using the TSC library, you can get information about all the flows on a site, or get information about a specific flow. The flow resources for Tableau Server are defined in the FlowItem class. The class corresponds to the flow resources you can access using the Tableau Server REST API. The flow methods are based upon the endpoints for flows in the REST API and operate on the FlowItem class.
FlowItem class
FlowItem(project_id, name=None)
The FlowItem represents the flow resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for flows. When you create a new FlowItem instance, you must specify the project_id that the flow is associated with.
Attributes
| Name |
Description |
connections |
The list of data connections (ConnectionItem) for the specified flow. You must first call the populate_connections method to access this data. See the ConnectionItem class. |
created_at |
The date and time when the flow was created. |
description |
The description for the flow. |
dqws |
The list of data quality warnings for the flow. You must first call populate_dqw to access this data. |
id |
The identifier for the flow. You need this value to query a specific flow or to delete a flow with the get_by_id and delete methods. |
name |
The name of the flow. If not specified when publishing, the name of the published flow file is used. |
owner_id |
The identifier of the owner of the flow. |
permissions |
The permissions for the flow. You must first call populate_permissions to access this data. |
project_id |
The identifier of the project associated with the flow. You must provide this identifier when you create an instance of a FlowItem. |
project_name |
The name of the project associated with the flow. |
tags |
The tags (set of strings) that have been added to the flow. |
updated_at |
The date and time when the flow was last updated. |
webpage_url |
The URL of the flow as displayed in browsers. |
Example
import tableauserverclient as TSC
# Create new flow_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39'
new_flow = TSC.FlowItem('3a8b6148-493c-11e6-a621-6f3499394a39')
Source file: models/flow_item.py
Flows methods
The Tableau Server Client provides several methods for interacting with flow resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
Source file: server/endpoint/flows_endpoint.py
flows.delete
Removes the specified flow from Tableau Server.
REST API: Delete Flow
Parameters
| Name |
Description |
flow_id |
The identifier (id) for the FlowItem that you want to delete from the server. |
Exceptions
| Error |
Description |
Flow ID undefined |
Raises an exception if a valid flow_id is not provided. |
Version
Version 3.3 and later. See REST API versions.
flows.download
flows.download(flow_id, filepath=None)
Downloads the specified flow in .tfl or .tflx format.
REST API: Download Flow
Parameters
| Name |
Description |
flow_id |
The identifier (id) for the FlowItem that you want to download from the server. |
filepath |
(Optional) Downloads the file to the location you specify. If no location is specified (the default is filepath=None), the file is downloaded to the current working directory. |
Exceptions
| Error |
Description |
Flow ID undefined |
Raises an exception if a valid flow_id is not provided. |
Returns
The file path to the downloaded flow.
Version
Version 3.3 and later. See REST API versions.
Example
file_path = server.flows.download('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
print("\nDownloaded the file to {0}.".format(file_path))
flows.get
flows.get(req_options=None)
Returns all the flows for the site.
To get the connection information for each flow, you must first populate the FlowItem with connection information using the flows.populate_connections method.
REST API: Query Flows for Site
Parameters
| Name |
Description |
req_options |
(Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific flow, you could specify the name of the project or its id. |
Returns
Returns a list of FlowItem objects and a PaginationItem object. Use these values to iterate through the results.
Version
Version 3.3 and later. See REST API versions.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
all_flows, pagination_item = server.flows.get()
print("\nThere are {} flows on site: ".format(pagination_item.total_available))
print([flow.name for flow in all_flows])
flows.get_by_id
Returns the specified flow item.
REST API: Query Flow
Parameters
| Name |
Description |
flow_id |
The flow_id specifies the flow to query. |
Exceptions
| Error |
Description |
Flow ID undefined |
Raises an exception if a valid flow_id is not provided. |
Returns
Returns a FlowItem.
Version
Version 3.3 and later. See REST API versions.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
print(flow.name)
flows.populate_connections
flows.populate_connections(flow_item)
Populates a FlowItem with connection information.
This method retrieves the connection information for the specified flow. The method requires a FlowItem object and populates its connections property with a list of ConnectionItem objects. You must call this method before you can access the connections property of a FlowItem.
REST API: Query Flow Connections
Parameters
| Name |
Description |
flow_item |
The flow_item specifies the flow to populate with connection information. |
Exceptions
| Error |
Description |
Flow item missing ID. Flow must be retrieved from server first. |
Raises an exception if the flow_item does not have an id. The flow_item must be retrieved from the server first. |
Version
Version 3.3 and later. See REST API versions.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.flows.populate_connections(flow)
for connection in flow.connections:
print(connection.id)
flows.publish
flows.publish(flow_item, file, mode, connections=None)
Publishes a flow to Tableau Server.
REST API: Publish Flow
Parameters
| Name |
Description |
flow_item |
The flow_item specifies the flow you are publishing. The flow_item must have a project_id set. |
file |
The file path or file object of the flow to publish. Only .tfl and .tflx files are supported. |
mode |
Specifies whether you are publishing a new flow (CreateNew), or overwriting an existing one (Overwrite). You cannot use Append with flows. |
connections |
(Optional) A list of ConnectionItem objects for connections in the flow that require credentials. |
Exceptions
| Error |
Description |
Invalid mode defined. |
Raises an error if the mode specified is not valid. |
File path does not lead to an existing file. |
Raises an error if the file path specified does not point to a valid file. |
Only .tfl, .tflx files can be published as flows. |
Raises an error if the type of file specified is not supported. |
Returns
Returns a FlowItem representing the published flow.
Version
Version 3.3 and later. See REST API versions.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
project_id = 'cc867571-b4e0-4764-8083-84b9f3aa8543'
new_flow = TSC.FlowItem(project_id)
new_flow = server.flows.publish(new_flow, 'path/to/flow.tflx', TSC.Server.PublishMode.Overwrite)
print("Published flow ID: {0}".format(new_flow.id))
flows.refresh
Runs the specified flow and returns a JobItem to track the progress of the run.
REST API: Run Flow Now
Parameters
| Name |
Description |
flow_item |
The FlowItem to run. |
Returns
Returns a JobItem. Use the jobs.wait_for_job method to block until the job is complete.
Version
Version 3.3 and later. See REST API versions.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
job = server.flows.refresh(flow)
server.jobs.wait_for_job(job)
flows.update
Modifies an existing flow. Use this method to change the owner or project of a flow, or to update its tags.
REST API: Update Flow
Parameters
| Name |
Description |
flow_item |
The FlowItem with updated attributes. Must have been retrieved from the server (must have an id). |
Exceptions
| Error |
Description |
Flow item missing ID. Flow must be retrieved from server first. |
Raises an exception if the flow_item does not have an id. |
Returns
Returns the updated FlowItem.
Version
Version 3.3 and later. See REST API versions.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
flow.project_id = 'new-project-id'
updated_flow = server.flows.update(flow)
flows.update_connection
flows.update_connection(flow_item, connection_item)
Updates the server address, port, username, or password for the specified flow connection.
REST API: Update Flow Connection
Parameters
| Name |
Description |
flow_item |
The FlowItem to update. |
connection_item |
The ConnectionItem with updated attributes. |
Returns
Returns the updated ConnectionItem.
Version
Version 3.3 and later. See REST API versions.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.flows.populate_connections(flow)
connection = flow.connections[0]
connection.server_address = 'new-server.example.com'
updated_connection = server.flows.update_connection(flow, connection)
Workload Identity Federation (WIF): setting connection_item.workgroup_auth_mode (and, for impersonation, connection_item.auth_federation_service_account) emits the matching attributes on the request payload via the shared Connection.update_req builder. Server-side handling of WIF on flow connections is governed by the flow endpoint and may differ from workbook and datasource behavior.
flows.populate_permissions
flows.populate_permissions(flow_item)
Populates the permissions for the specified flow.
Parameters
| Name |
Description |
flow_item |
The FlowItem to populate with permissions. |
Version
Version 3.3 and later. See REST API versions.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.flows.populate_permissions(flow)
for permission in flow.permissions:
print(permission.grantee_id, permission.capabilities)
flows.update_permissions
flows.update_permissions(flow_item, permission_item)
Adds or updates permissions for the specified flow.
Parameters
| Name |
Description |
flow_item |
The FlowItem to update permissions for. |
permission_item |
A list of PermissionsRule objects representing the permissions to add or update. |
Version
Version 3.3 and later. See REST API versions.
flows.delete_permission
flows.delete_permission(flow_item, capability_item)
Removes a permission from the specified flow.
Parameters
| Name |
Description |
flow_item |
The FlowItem to remove the permission from. |
capability_item |
The PermissionsRule object representing the permission to remove. |
Version
Version 3.3 and later. See REST API versions.
flows.populate_dqw
flows.populate_dqw(flow_item)
Populates the data quality warnings for the specified flow.
Parameters
| Name |
Description |
flow_item |
The FlowItem to populate with data quality warnings. |
Version
Version 3.5 and later. See REST API versions.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.flows.populate_dqw(flow)
for dqw in flow.dqws:
print(dqw.message)
flows.add_dqw
flows.add_dqw(flow_item, warning)
Adds a data quality warning to the specified flow.
Parameters
| Name |
Description |
flow_item |
The FlowItem to add the data quality warning to. |
warning |
The DQWItem object representing the data quality warning to add. |
Version
Version 3.5 and later. See REST API versions.
flows.update_dqw
flows.update_dqw(flow_item, warning)
Updates a data quality warning on the specified flow.
Parameters
| Name |
Description |
flow_item |
The FlowItem to update the data quality warning on. |
warning |
The DQWItem object representing the updated data quality warning. |
Version
Version 3.5 and later. See REST API versions.
flows.delete_dqw
flows.delete_dqw(flow_item)
Removes all data quality warnings from the specified flow.
Parameters
| Name |
Description |
flow_item |
The FlowItem to remove data quality warnings from. |
Version
Version 3.5 and later. See REST API versions.
flows.schedule_flow_run
flows.schedule_flow_run(schedule_id, item)
Convenience method to add a flow to an existing schedule.
Parameters
| Name |
Description |
schedule_id |
The identifier of the schedule to add the flow to. |
item |
The FlowItem to add to the schedule. |
Returns
Returns a list of AddResponse objects.
Version
Version 3.3 and later. See REST API versions.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
result = server.flows.schedule_flow_run('schedule-id-here', flow)
flows.filter
Returns a list of flows that match the specified filters. Fields and operators are passed as keyword arguments in the form field_name=value or field_name__operator=value.
Supported fields and operators
| Field |
Operators |
created_at |
eq, gt, gte, lt, lte |
name |
eq, in |
owner_name |
eq |
project_id |
eq |
project_name |
eq, in |
updated |
eq, gt, gte, lt, lte |
Returns
Returns a QuerySet of FlowItem objects.
Example
matching_flows = server.flows.filter(project_name='My Project')
for flow in matching_flows:
print(flow.name)
Flow Runs
Using the TSC library, you can query flow runs on a site, get details about a specific flow run, cancel a running flow, or wait for a flow run to complete. Flow runs are created when a flow is triggered to run, either manually or on a schedule.
The flow run resources for Tableau Server are defined in the FlowRunItem class. The class corresponds to the flow run resources you can access using the Tableau Server REST API.
FlowRunItem class
The FlowRunItem represents the result of a flow run on Tableau Server. Instances of this class are returned by the flow run methods; you do not create them directly.
Attributes
| Name |
Description |
id |
The identifier for the flow run. |
flow_id |
The identifier of the flow that was run. |
status |
The current status of the flow run. Possible values include Success, Failed, and Cancelled. |
started_at |
The date and time when the flow run started. |
completed_at |
The date and time when the flow run completed. Is None if the run is still in progress. |
progress |
The progress percentage of the flow run. |
background_job_id |
The identifier of the background job associated with the flow run. |
Source file: models/flow_run_item.py
Flow Runs methods
The Tableau Server Client provides several methods for interacting with flow run resources. These methods correspond to endpoints in the Tableau Server REST API.
Source file: server/endpoint/flow_runs_endpoint.py
flow_runs.get
flow_runs.get(req_options=None)
Returns all flow runs on the site.
REST API: Get Flow Runs
Parameters
| Name |
Description |
req_options |
(Optional) You can pass the method a request object that contains additional parameters to filter the request. |
Returns
Returns a list of FlowRunItem objects. Be aware that flowruns.get does NOT return a PaginationItem.
Version
Version 3.10 and later. See REST API versions.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
all_runs, pagination_item = server.flow_runs.get()
print("\nThere are {} flow runs on site.".format(pagination_item.total_available))
for run in all_runs:
print(run.id, run.status)
flow_runs.get_by_id
flow_runs.get_by_id(flow_run_id)
Returns the specified flow run item.
REST API: Get Flow Run
Parameters
| Name |
Description |
flow_run_id |
The identifier (id) for the FlowRunItem to query. |
Exceptions
| Error |
Description |
Flow ID undefined |
Raises an exception if a valid flow_run_id is not provided. |
Returns
Returns a FlowRunItem.
Version
Version 3.10 and later. See REST API versions.
Example
flow_run = server.flow_runs.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
print(flow_run.status, flow_run.progress)
flow_runs.cancel
flow_runs.cancel(flow_run_id)
Cancels the specified flow run.
REST API: Cancel Flow Run
Parameters
| Name |
Description |
flow_run_id |
The identifier (id) for the FlowRunItem to cancel. Can be the id string or a FlowRunItem object. |
Exceptions
| Error |
Description |
Flow ID undefined |
Raises an exception if a valid flow_run_id is not provided. |
Version
Version 3.10 and later. See REST API versions.
Example
flow_run = server.flow_runs.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
server.flow_runs.cancel(flow_run.id)
flow_runs.wait_for_job
flow_runs.wait_for_job(flow_run_id, *, timeout=None)
Waits for the specified flow run to complete and returns the finished FlowRunItem. This method polls the server repeatedly using exponential backoff until the run completes, then raises an exception if it failed or was cancelled.
Parameters
| Name |
Description |
flow_run_id |
The identifier (id) for the flow run to wait for. Can be the id string or a FlowRunItem object. |
timeout |
(Optional) The maximum number of seconds to wait before raising a timeout error. If not specified, waits indefinitely. |
Exceptions
| Error |
Description |
FlowRunFailedException |
Raised if the flow run completes with a Failed status. |
FlowRunCancelledException |
Raised if the flow run completes with a Cancelled status. |
Returns
Returns the completed FlowRunItem if the run succeeded.
Version
Version 3.10 and later. See REST API versions.
Example
# Trigger a flow run and wait for it to finish
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
job = server.flows.refresh(flow)
# Wait for the resulting flow run to complete
flow_run = server.flow_runs.wait_for_job(job.id, timeout=300)
print("Flow run completed with status: {}".format(flow_run.status))
flow_runs.filter
flow_runs.filter(**kwargs)
Returns a list of flow runs that match the specified filters. Fields and operators are passed as keyword arguments in the form field_name=value or field_name__operator=value.
Supported fields and operators
| Field |
Operators |
complete_at |
eq, gt, gte, lt, lte |
flow_id |
eq, in |
progress |
eq, gt, gte, lt, lte |
started_at |
eq, gt, gte, lt, lte |
user_id |
eq, in |
Returns
Returns a QuerySet of FlowRunItem objects.
Example
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
recent_runs = server.flow_runs.filter(flow_id=flow.id)
for run in recent_runs:
print(run.id, run.status)
Groups
Using the TSC library, you can get information about all the groups on a site, you can add or remove groups, or add or remove users in a group.
The group resources for Tableau Server are defined in the GroupItem class. The class corresponds to the group resources you can access using the Tableau Server REST API. The group methods are based upon the endpoints for groups in the REST API and operate on the GroupItem class.
GroupItem class
The GroupItem class contains the attributes for the group resources on Tableau Server. The GroupItem class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
Source file: models/group_item.py
Attributes
| Name |
Description |
domain_name |
The name of the Active Directory domain (local if local authentication is used). |
id |
The id of the group. |
users |
The list of users (UserItem). |
name |
The name of the group. The name is required when you create an instance of a group. |
minimum_site_role |
The role to grant users that are added to the group. |
license_mode |
The mode defining when to apply licenses for group members. When the mode is onLogin, a license is granted for each group member when they login to a site. When the mode is onSync, a license is granted for group members each time the domain is synced. |
Example
newgroup = TSC.GroupItem('My Group')
# call groups.create() with new group
Groups methods
The Tableau Server Client provides several methods for interacting with group resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
Source file: server/endpoint/groups_endpoint.py
groups.add_user
groups.add_user(group_item, user_id):
Adds a user to the specified group.
REST API Add User to Group
Parameters
| Name |
Description |
group_item |
The group_item specifies the group to update. |
user_id |
The id of the user. |
Returns
None.
Example
# Adding a user to a group
#
# get the group item
all_groups, pagination_item = server.groups.get()
mygroup = all_groups[1]
# The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba'
# add Ian to the group
server.groups.add_user(mygroup, '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba')
groups.add_users
groups.add_users(group_item, user_id):
Adds multiple users to the specified group.
REST API Add User to Group
Version
This endpoint is available with REST API version 3.21 and up. Method added in
version v0.33
Parameters
| Name |
Description |
group_item |
The group_item specifies the group to update. |
users |
An Iterable of UserItems, or user ids. |
Returns
list[UserItem]
Example
# Adding a user to a group
#
# get the group item
all_groups, pagination_item = server.groups.get()
mygroup = all_groups[1]
# Add Viewers to the group
added_users = server.groups.add_users(
mygroup,
server.users.filter(site_role=TSC.UserItem.Roles.Viewer)
)
groups.create
Creates a new local group in Tableau Server.
REST API: Create Group
Parameters
| Name |
Description |
group_item |
The group_item specifies the group to add. You first create a new instance of a GroupItem and pass that to this method. |
Returns
Adds new GroupItem.
Example
# Create a new group
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('https://SERVERURL')
# create a new instance with the group name
newgroup = TSC.GroupItem('My Group')
newgroup.minimum_site_role = TSC.UserItem.Roles.ExplorerCanPublish
# call the create method
newgroup = server.groups.create(newgroup)
# print the names of the groups on the server
all_groups, pagination_item = server.groups.get()
for group in all_groups :
print(group.name, group.id)
groups.create_AD_group
create_AD_group(group_item, asJob=False)
Creates an active directory group in Tableau Server.
REST API: Create Group
Parameters
| Name |
Description |
group_item |
The group_item specifies the group to add. You first create a new instance of a GroupItem and pass that to this method. |
asJob |
Boolean flag used to specify an asynchronous operation. If set to True, the return value will be a JobItem containing the status of the queued job. See JobItem class. |
Returns
Returns the created GroupItem or a JobItem if asJob flag was set to True.
Example
# Create a new group
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('https://SERVERURL')
# create a new instance with the group name
newgroup = TSC.GroupItem('AD_Group_Name', 'AD_Domain_Name')
newgroup.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
newgroup.license_mode = TSC.GroupItem.LicenseMode.onSync
# call the create method
newgroup = server.groups.create_AD_group(newgroup)
# call the create method asynchronously
newgroup_job = server.groups.create_AD_group(newgroup, asJob=True)
groups.delete
Deletes the group on the site.
REST API: Delete Group
Parameters
| Name |
Description |
group_id |
The identifier (id) for the group that you want to remove from the server. |
Exceptions
| Error |
Description |
Group ID undefined |
Raises an exception if a valid group_id is not provided. |
Example
# Delete a group from the site
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
server.groups.delete('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
groups.get
groups.get(req_options=None)
Returns information about the groups on the site.
To get information about the users in a group, you must first populate the GroupItem with user information using the groups.populate_users method.
REST API: Get Users on Site
Parameters
| Name |
Description |
req_options |
(Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific group, you could specify the name of the group or the group id. |
Returns
Returns a list of GroupItem objects and a PaginationItem object. Use these values to iterate through the results.
Example
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
# get the groups on the server
all_groups, pagination_item = server.groups.get()
# print the names of the first 100 groups
for group in all_groups :
print(group.name, group.id)
groups.populate_users
groups.populate_users(group_item, req_options=None)
Populates the group_item with the list of users.
REST API: Get Users in Group
Parameters
| Name |
Description |
group_item |
The group_item specifies the group to populate with user information. |
req_options |
(Optional) Additional request options to send to the endpoint. |
Exceptions
Group item missing ID. Group must be retrieved from server first. : Raises an error if the group_item is unspecified.
Returns
None. A list of UserItem objects are added to the group (group_item.users).
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://SERVERURL')
#
...
# get the group
all_groups, pagination_item = server.groups.get()
mygroup = all_groups[1]
# get the user information
pagination_item = server.groups.populate_users(mygroup)
# print the names of the users
for user in mygroup.users :
print(user.name)
groups.remove_user
groups.remove_user(group_item, user_id)
Removes a user from a group.
REST API: Remove User from Group
Parameters
| Name |
Description |
group_item |
The group_item specifies the group to remove the user from. |
user_id |
The id for the user. |
Exceptions
| Error |
Description |
Group must be populated with users first. |
Raises an error if the group_item is unpopulated. |
Returns
None. The user is removed from the group.
Example
# Remove a user from a group
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
# get a group
all_groups, pagination_item = server.groups.get()
mygroup = all_groups[0]
# remove user '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d'
server.groups.remove_user(mygroup, '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
groups.remove_users
groups.remove_users(group_item, user_id):
Removes multiple users from the specified group.
REST API Remove User from Group
Version
This endpoint is available with REST API version 3.21 and up. Method added in
version v0.33
Parameters
| Name |
Description |
group_item |
The group_item specifies the group to update. |
users |
An Iterable of UserItems, or user ids. |
Returns
None
Example
# Removing a user from a group
#
# get the group item
all_groups, pagination_item = server.groups.get()
mygroup = all_groups[1]
# Remove Viewers from the group
server.groups.remove_users(
mygroup,
server.users.filter(site_role=TSC.UserItem.Roles.Viewer)
)
groups.update
groups.update(group_item, as_job=False)
Updates a group in Tableau Server.
REST API: Update Group
Parameters
| Name |
Description |
group_item |
The group_item specifies the group to update. |
as_job |
(Optional) If this value is set to True, the update operation will be asynchronous and return a JobItem. This is only supported for Active Directory groups. By default, this value is set to False. |
Exceptions
| Error |
Description |
Group item missing ID. |
Raises an error if the group_item is missing the id attribute. |
Local groups cannot be updated asynchronously. |
The as_job attribute was set to True for a local group. |
Returns
The updated GroupItem object. If as_job was set to True, a JobItem will be returned instead.
Example
# Fetch an existing group from server.
groups, pagination = server.groups.get()
group = groups[0]
# Set update-able fields. Any of these can be added or removed.
## Local group
group.name = "new group name"
group.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
## Active Directory group
group.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
group.license_mode = TSC.GroupItem.LicenseMode.onLogin
# Update group - synchronous
group = server.groups.update(group)
# Update group - asynchronous (only for Active Directory groups)
job = server.groups.update(group, as_job=True)
GroupSets
Using the TSC library, you can get information about all the group sets on a site, create or delete group sets, and add or remove groups from a group set.
The group set resources for Tableau Server are defined in the GroupSetItem class. The class corresponds to the group set resources you can access using the Tableau Server REST API. The group set methods are based upon the endpoints for group sets in the REST API and operate on the GroupSetItem class.
GroupSetItem class
The GroupSetItem class contains the attributes for the group set resources on Tableau Server. The GroupSetItem class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
Source file: models/groupset_item.py
Attributes
| Name |
Description |
id |
The id of the group set. |
name |
The name of the group set. The name is required when you create an instance of a group set. |
groups |
The list of groups (GroupItem) that belong to this group set. |
group_count |
The number of groups in the group set. |
Example
new_groupset = TSC.GroupSetItem('My Group Set')
# call groupsets.create() with new group set
groupset = server.group_sets.create(new_groupset)
GroupSets methods
The Tableau Server Client provides several methods for interacting with group set resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
Source file: server/endpoint/groupsets_endpoint.py
group_sets.get
group_sets.get(req_options=None, result_level=None)
Returns information about the group sets on the specified site.
REST API: Get Group Sets
Version
This endpoint is available with REST API version 3.22 and up.
Parameters
| Name |
Description |
req_options |
(Optional) You can pass the method a request object that contains additional parameters to filter the request. Filter parameters can include page_size and page_number. |
result_level |
(Optional) Specifies the level of detail in the response. Can be "members" to include member groups, or "local" for local group sets only. |
Returns
Returns a list of GroupSetItem objects and a PaginationItem object.
Example
all_groupsets, pagination_item = server.group_sets.get()
for groupset in all_groupsets:
print(groupset.id, groupset.name)
group_sets.get_by_id
group_sets.get_by_id(groupset_id)
Returns information about the specified group set.
REST API: Get Group Set
Version
This endpoint is available with REST API version 3.22 and up.
Parameters
| Name |
Description |
groupset_id |
The id of the group set. |
Returns
Returns a GroupSetItem object.
Example
groupset = server.group_sets.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
print(groupset.name)
group_sets.create
group_sets.create(groupset_item)
Creates a new group set on the specified site.
REST API: Create Group Set
Version
This endpoint is available with REST API version 3.22 and up.
Parameters
| Name |
Description |
groupset_item |
The GroupSetItem specifies the group set to add. You first create a new instance of a GroupSetItem and pass that to this method. |
Returns
Returns the newly created GroupSetItem object.
Example
new_groupset = TSC.GroupSetItem('My Group Set')
created_groupset = server.group_sets.create(new_groupset)
print(created_groupset.id)
group_sets.update
group_sets.update(groupset_item)
Modifies an existing group set. You can use this method to rename a group set.
REST API: Update Group Set
Version
This endpoint is available with REST API version 3.22 and up.
Parameters
| Name |
Description |
groupset_item |
The GroupSetItem to update. The group set item must have a valid id. |
Returns
Returns the updated GroupSetItem object.
Example
groupset.name = 'Renamed Group Set'
updated_groupset = server.group_sets.update(groupset)
group_sets.delete
group_sets.delete(groupset)
Deletes the specified group set from the site.
REST API: Delete Group Set
Version
This endpoint is available with REST API version 3.22 and up.
Parameters
| Name |
Description |
groupset |
The GroupSetItem or group set id (str) to delete. |
Returns
None.
Example
server.group_sets.delete(groupset.id)
group_sets.add_group
group_sets.add_group(groupset_item, group)
Adds a group to the specified group set.
REST API: Add Group to Group Set
Version
This endpoint is available with REST API version 3.22 and up.
Parameters
| Name |
Description |
groupset_item |
The GroupSetItem specifying the group set to update. |
group |
The GroupItem or group id (str) to add to the group set. |
Returns
None.
Example
all_groups, _ = server.groups.get()
mygroup = all_groups[0]
server.group_sets.add_group(groupset, mygroup)
group_sets.remove_group
group_sets.remove_group(groupset_item, group)
Removes a group from the specified group set.
REST API: Remove Group from Group Set
Version
This endpoint is available with REST API version 3.22 and up.
Parameters
| Name |
Description |
groupset_item |
The GroupSetItem specifying the group set to update. |
group |
The GroupItem or group id (str) to remove from the group set. |
Returns
None.
Example
server.group_sets.remove_group(groupset, mygroup)
group_sets.filter
group_sets.filter(**kwargs)
Returns a list of group sets that match the specified filters. Fields and operators are passed as keyword arguments in the form field_name=value or field_name__operator=value.
Version
This endpoint is available with REST API version 3.22 and up.
Supported fields and operators
| Field |
Operators |
domain_name |
eq, in |
domain_nickname |
eq, in |
is_external_user_enabled |
eq |
is_local |
eq |
luid |
eq, in |
minimum_site_role |
eq, in |
name |
eq, cieq, in, like |
user_count |
eq, gt, gte, lt, lte |
Returns
Returns a QuerySet of GroupSetItem objects.
Example
local_groupsets = server.group_sets.filter(is_local=True)
for groupset in local_groupsets:
print(groupset.name)
Jobs
Using the TSC library, you can get information about an asynchronous process (or job) on the server. These jobs can be created when Tableau runs certain tasks that could be long running, such as importing or synchronizing users from Active Directory, or running an extract refresh. For example, the REST API methods to create or update groups, to run an extract refresh task, or to publish workbooks can take an asJob parameter (asJob-true) that creates a background process (the job) to complete the call. Information about the asynchronous job is returned from the method.
If you have the identifier of the job, you can use the TSC library to find out the status of the asynchronous job.
The job properties are defined in the JobItem class. The class corresponds to the properties for jobs you can access using the Tableau Server REST API. The job methods are based upon the endpoints for jobs in the REST API and operate on the JobItem class.
JobItem class
JobItem(id, type, created_at, started_at=None, completed_at=None, finish_code=0)
The JobItem class contains information about the specified job running on Tableau Server. The JobItem class defines the information you can query from Tableau Server. The class members correspond to the attributes of a server response payload.
Source file: models/job_item.py
Attributes
| Name |
Description |
id |
The id of the job. |
type |
The type of task. The types correspond to the job type categories listed for the Query Job REST API. |
created_at |
The time the job was created. |
started_at |
The time the job started. |
completed_at |
The time the job finished. |
finish_code |
The return code from job. |
progress |
The progress of the job. |
notes |
The notes of the job. |
mode |
The mode of the job. |
Jobs methods
The Jobs methods are based upon the endpoints for jobs in the REST API and operate on the JobItem class.
Source files: server/endpoint/jobs_endpoint.py
jobs.get
jobs.get(job_id=None, req_options=None)
Retrieve jobs for the site. Endpoint is paginated and will return a list of jobs and pagination information. If a job_id is provided, the method will return information about that specific job. Specifying a job_id is deprecated and will be removed in a future version.
REST API: Get Background Jobs on Site
Parameters
| Name |
Description |
job_id |
(Optional) The job_id specifies the job to query. When provided, returns the status of that specific job. |
req_options |
(Optional) You can pass the method a request object that contains additional parameters to filter the request. |
Returns
Returns a list of BackgroundJobItem objects and a PaginationItem object.
Version
Version 2.6 and later. See REST API versions.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
all_jobs, pagination_item = server.jobs.get()
print("\nThere are {} jobs on site: ".format(pagination_item.total_available))
print([job.id for job in all_jobs])
jobs.get_by_id
Gets information about the specified job.
REST API: Query Job
Parameters
| Name |
Description |
job_id |
The job_id specifies the id of the job that is returned from an asynchronous task, such as extract refresh, or an import or update to groups using Active Directory |
Exceptions
| Error |
Description |
404018 Resource Not Found |
Raises an error if the job_id is not found. |
Returns
Returns the JobItem requested.
Example
# Query a Job
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
# get the id of the job from response to extract refresh task,
# or another asynchronous REST API call.
# in this case, "576b616d-341a-4539-b32c-1ed0eb9db548"
myJobId = '576b616d-341a-4539-b32c-1ed0eb9db548'
jobinfo = server.jobs.get_by_id(myJobId)
print(jobinfo)
# <Job#576b616d-341a-4539-b32c-1ed0eb9db548 RefreshExtract created_at(2018-04-10T23:43:21Z) started_at(2018-04-10T23:43:25Z) completed_at(2018-04-10T23:43:26Z) finish_code(1)>
jobs.cancel
Cancels the currently running job. Can be used to cancel currently running jobs like extract refreshes.
Parameters
| Name |
Description |
job_id |
The job_id specifies the id of the job that we want to cancel. It is the id of the job that is retunred from an asynchronous taks, such as extract refresh, run a flow, or import or update to groups using Active Directory. |
Exceptions
| Error |
Description |
| 404 Resource Not Found |
Raises an error if the job_id is not found. |
Returns Returns the details of the canceled job including the URL of the site where the job was created.
Example
# Query a Job
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
# get the id of the job from response from the query job method.
# in this example, "576b781d-331c-4539-b61d-1ed0eb9db548"
cancelJobId = '576b781d-331c-4539-b61d-1ed0eb9db548'
jobs.cancel (cancelJobId)
jobs.wait_for_job
jobs.wait_for_job(job_id, *, timeout=None)
Waits until a given job succesfully finishes.
Repeatedly polls the server using jobs.get_by_id until the job completed.
It uses an exponentially increasing sleep time between polls to guarantee a snappy response time for fast-running jobs while not putting overly large load on the server for long-running jobs.
In case the job fails or is cancelled, wait_for_job will raise an exception.
Parameters
| Name |
Description |
job_id |
The job_id specifies the id of the job that we want to wait for |
timeout |
Optional timeout interval in seconds. wait_for_job will raise a TimeoutError if the job is not finished after waiting for timeout seconds. |
Returns
Returns the final JobItem.
Usually, you can just discard the return value without checking the job status. In case the job wasn’t succesful, wait_for_job would have already raised an exception. For advanced scenarios, the returned JobItem might still be interesting to access e.g. start and end time or notes.
Example
See the update_datasource_data.py or refresh.py sample in the Samples directory.
jobs.filter
Returns a list of background jobs that match the specified filters. Fields and operators are passed as keyword arguments in the form field_name=value or field_name__operator=value.
Supported fields and operators
| Field |
Operators |
args |
has |
completed_at |
eq, gt, gte, lt, lte |
created_at |
eq, gt, gte, lt, lte |
job_type |
eq, in |
notes |
has |
priority |
eq, gt, gte, lt, lte |
progress |
eq, gt, gte, lt, lte |
started_at |
eq, gt, gte, lt, lte |
status |
eq |
subtitle |
eq, has |
title |
eq, has |
Returns
Returns a QuerySet of BackgroundJobItem objects.
Example
failed_jobs = server.jobs.filter(status='Failed')
for job in failed_jobs:
print(job.id, job.type)
Metadata
Using the metadata endpoint, one can use GraphQL to query metadata on, e.g., workbooks, datasources, the fields contained within them, and the relationships between them.
Metadata methods
The Metadata methods call the Metadata API which is a GraphQL interface allowing to query metadata about objects on the server (workbooks, datasources, …) and the relationships between them.
Source files: server/endpoint/metadata_endpoint.py
metadata.query
metadata.query(query, variables=None, abort_on_error=False)
Executes a metadata query and returns the result.
Parameters
| Name |
Description |
query |
The GraphQL query |
variables |
Variables for the GraphQL query |
abort_on_error |
Whether to throw an exception on error |
Returns
The method returns the query results as a stucture of lists and dicts as returned by the json package.
Example
See the metadata_query.py sample in the Samples directory.
metadata.paginated_query
metadata.paginated_query(query, variables=None, abort_on_error=False)
Executes a metadata query, and returns a dictionary containing a list of the results. In order to properly paginate through all the results, the query must contain a field pageInfo with the subfields hasNextPage and endCursor, as well as the nodes to be returned. The query must accept the variables first (the number of items to return) and afterToken (the cursor after which to return items). The method will repeatedly call the metadata endpoint until all results have been retrieved, and return a dictionary containing a list of all results.
Parameters
| Name |
Description |
query |
The GraphQL query |
variables |
Variables for the GraphQL query |
abort_on_error |
Whether to throw an exception on error |
Returns
The method returns the query results in a dictionary containing a list of pages as a stucture of lists and dicts as returned by the json package.
Example
See the metadata_paginated_query.py sample in the Samples directory.
Metrics
Using the TSC library, you can get information about all metrics on a site, update, or delete metrics.
MetricItem class
MetricItem(name: Optional[str]=None)
The metrics resources for Tableau are defined in the MetricItem class. The class corresponds to the metric resource you can access using the Tableau Server REST API.
Attributes
Name | Description
:— | :—
name | Name of the metric
id | The REST API id for the metric
description | The description of the metric
webpage_url | The URL for the metric
created_at | The datetime object for when the metric was created
updated_at | The datetime object for when the metric was updated
suspended | Boolean for if the metric is in a suspended state
project_id | REST API id for the project containing the metric
project_name | The name of the project containing the metric
owner_id | REST API id for the user who owns the metric
view_id | REST API id for the view from which the metric was created
Source file: models/metric_item.py
Metric methods
The metric methods are based upon the endpoints for metrics in the REST API and operate on the MetricItem class. The metrics endpoint also supports the django style filtering.
See Filter and Sort for more information.
Source files: server/endpoint/metrics_endpoint.py
metrics.delete
metrics.delete(metric_id)
Deletes a metric item from a site.
To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.
REST API: Delete Metric
Parameters
| Name |
Description |
metric_id |
The id of the metric to delete |
Returns
None
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc
server.metrics.delete("6561daa3-20e8-407f-ba09-709b178c0b4a")
metrics.get
Return a list of metrics items for a site.
To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.
REST API: List Metrics for Site
Parameters
None.
Returns
Returns a Tuple containing a list of all MetricItem objects and a PaginationItem. Use these values to iterate through the results.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
server = TSC.Server('https://SERVER')
with server.auth.sign_in(tableau_auth):
# get all metrics on site
all_metric_items, pagination_item = server.metrics.get()
print([metric.name for metric in all_metric_items])
metrics.get_by_id
metrics.get_by_id(metric_id)
Return a specific metric item from the site.
To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.
REST API: Get Metric
Parameters
| Name |
Description |
metric_id |
The id of the desired metric |
Returns
Returns a MetricItem object corresponding to the ID requested.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc
server.metrics.get_by_id("6561daa3-20e8-407f-ba09-709b178c0b4a")
metrics.update
Updates a metric item on the Tableau Server.
To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.
REST API: Update Metric
Parameters
| Name |
Description |
metric_item |
The altered MetricItem to be updated on the Tableau Server |
Returns
Returns a MetricItem object reflecting the changes applied to Tableau Server.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc
metric = server.metrics.get_by_id("6561daa3-20e8-407f-ba09-709b178c0b4a")
metric.owner_id = "1bbbc2b9-847d-443c-9a1f-dbcf112b8814"
server.metrics.update(metric)
Projects
Using the TSC library, you can get information about all the projects on a site, or you can create, update projects, or remove projects.
The project resources for Tableau are defined in the ProjectItem class. The class corresponds to the project resources you can access using the Tableau Server REST API. The project methods are based upon the endpoints for projects in the REST API and operate on the ProjectItem class.
ProjectItem class
ProjectItem(name, description=None, content_permissions=None, parent_id=None)
The project resources for Tableau are defined in the ProjectItem class. The class corresponds to the project resources you can access using the Tableau Server REST API.
Attributes
| Name |
Description |
content_permissions |
Sets or shows the permissions for the content in the project. The options are either LockedToProject, ManagedByOwner or LockedToProjectWithoutNested. |
name |
Name of the project. |
description |
The description of the project. |
id |
The project id. |
parent_id |
The id of the parent project. Use this option to create project hierarchies. For information about managing projects, project hierarchies, and permissions, see Use Projects to Manage Content Access. |
Source file: models/project_item.py
ProjectItem.ContentPermissions
The ProjectItem class has a sub-class that defines the permissions for the project (ProjectItem.ContentPermissions). The options are LockedToProject, ManagedByOwner and LockedToProjectWithoutNested. For information on these content permissions, see Lock Content Permissions to the Project.
| Name |
Description |
ProjectItem.ContentPermissions.LockedToProject |
Locks all content permissions to the project. |
ProjectItem.ContentPermissions.ManagedByOwner |
Users can manage permissions for content that they own. This is the default. |
ProjectItem.ContentPermissions.LockedToProjectWithoutNested |
Lock the permissions of a parent project, but not those of its child projects. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc
locked_true = TSC.ProjectItem.ContentPermissions.LockedToProject
print(locked_true)
# prints 'LockedToProject'
by_owner = TSC.ProjectItem.ContentPermissions.ManagedByOwner
print(by_owner)
# prints 'ManagedByOwner'
# pass the content_permissions to new instance of the project item.
new_project = TSC.ProjectItem(name='My Project', content_permissions=by_owner, description='Project example')
Project methods
The project methods are based upon the endpoints for projects in the REST API and operate on the ProjectItem class.
Source files: server/endpoint/projects_endpoint.py
projects.create
projects.create(project_item)
Creates a project on the specified site.
To create a project, you first create a new instance of a ProjectItem and pass it to the create method. To specify the site to create the new project, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.
REST API: Create Project
Parameters
| Name |
Description |
project_item |
Specifies the properties for the project. The project_item is the request package. To create the request package, create a new instance of ProjectItem. |
Returns
Returns the new project item.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
server = TSC.Server('https://SERVER')
with server.auth.sign_in(tableau_auth):
# create project item
new_project = TSC.ProjectItem(name='Example Project', content_permissions='LockedToProject', description='Project created for testing')
# create the project
new_project = server.projects.create(new_project)
projects.get
Return a list of project items for a site.
To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.
REST API: Query Projects
Parameters
None.
Returns
Returns a list of all ProjectItem objects and a PaginationItem. Use these values to iterate through the results.
Example
import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
server = TSC.Server('https://SERVER')
with server.auth.sign_in(tableau_auth):
# get all projects on site
all_project_items, pagination_item = server.projects.get()
print([proj.name for proj in all_project_items])
projects.update
projects.update(project_item)
Modify the project settings.
You can use this method to update the project name, the project description, or the project permissions. To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.
REST API: Update Project
Parameters
| Name |
Description |
project_item |
The project item object must include the project ID. The values in the project item override the current project settings. |
Exceptions
| Error |
Description |
Project item missing ID. |
Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. |
Returns
Returns the updated project information.
See ProjectItem class
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc
...
# get list of projects
all_project_items, pagination_item = server.projects.get()
# update project item #7 with new name, etc.
my_project = all_projects[7]
my_project.name ='New name'
my_project.description = 'New description'
# call method to update project
updated_project = server.projects.update(my_project)
projects.delete
projects.delete(project_id)
Deletes a project by ID.
To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.
REST API: Delete Project
Parameters
| Name |
Description |
project_id |
The ID of the project to delete. |
Exceptions
| Error |
Description |
Project ID undefined. |
Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
server.projects.delete('1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e')
projects.populate_permissions
projects.populate_permissions(item)
Queries the project permissions, parses and stores the returned the permissions.
REST API: Query Project Permissions
Parameters
| Name |
Description |
item |
A project object. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
server.projects.populate_permissions(project_item)
projects.update_permissions
projects.update_permissions(item, rules)
Add project permissions for a user or group.
REST API: Add Project Permissions
Parameters
| Name |
Description |
item |
A project object. |
rules |
A list of PermissionsRule objects. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
project_capabilities = {
TSC.Permission.Capability.Read: TSC.Permission.Mode.Allow
}
project_rules = TSC.PermissionsRule(
grantee=project_item,
capabilities=project_capabilities
)
server.projects.update_permissions(project_item, [project_rules])
projects.delete_permission
projects.delete_permission(item, rules)
Delete project permissions.
REST API: Delete Project Permissions
Parameters
| Name |
Description |
item |
A project object. |
rules |
A list of PermissionsRule objects or a single PermissionsRule object. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
project_capabilities = {
TSC.Permission.Capability.Read: TSC.Permission.Mode.Allow
}
project_rules = TSC.PermissionsRule(
grantee=project_item,
capabilities=project_capabilities
)
server.projects.delete_permission(project_item)
projects.populate_workbook_default_permissions
projects.populate_workbook_default_permissions(item)
Queries the default workbook permissions, parses and stores the returned the permissions.
REST API: Query Default Permissions
Parameters
| Name |
Description |
item |
A project object. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
server.projects.populate_workbook_default_permissions(project_item)
projects.populate_datasource_default_permissions
projects.populate_datasource_default_permissions(item)
Queries the default datasource permissions, parses and stores the returned the permissions.
REST API: Query Default Permissions
Parameters
| Name |
Description |
item |
A project object. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
server.projects.populate_datasource_default_permissions(project_item)
projects.populate_flow_default_permissions
projects.populate_flow_default_permissions(item)
Queries the default flow permissions, parses and stores the returned the permissions.
REST API: Query Default Permissions
Parameters
| Name |
Description |
item |
A project object. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
server.projects.populate_flow_default_permissions(project_item)
projects.update_workbook_default_permissions
projects.update_workbook_default_permissions(item, rules)
Add or update default workbook permissions.
REST API: Add Default Workbook Permissions
Parameters
| Name |
Description |
item |
A project object. |
rules |
A list of PermissionsRule objects. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
capabilities = {
TSC.Permission.Capability.ViewComments: TSC.Permission.Mode.Allow
}
rules = TSC.PermissionsRule(
grantee=project_item,
capabilities=capabilities
)
server.projects.update_workbook_default_permissions(project_item, [rules])
projects.update_datasource_default_permissions
projects.update_datasource_default_permissions(item, rules)
Add or update default datasource permissions.
REST API: Add Default Datasource Permissions
Parameters
| Name |
Description |
item |
A project object. |
rules |
A list of PermissionsRule objects. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
capabilities = {
TSC.Permission.Capability.ExportXml: TSC.Permission.Mode.Allow
}
rules = TSC.PermissionsRule(
grantee=project_item,
capabilities=capabilities
)
server.projects.update_datasource_default_permissions(project_item, [rules])
projects.update_flow_default_permissions
projects.update_flow_default_permissions(item, rules)
Add or update default flow permissions.
REST API: Add Default Flow Permissions
Parameters
| Name |
Description |
item |
A project object. |
rules |
A list of PermissionsRule objects. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
capabilities = {
TSC.Permission.Capability.Read: TSC.Permission.Mode.Allow
}
rule = TSC.PermissionsRule(
grantee=project_item,
capabilities=capabilities
)
server.projects.update_flow_default_permissions(project_item, [rule])
projects.delete_workbook_default_permissions
projects.delete_workbook_default_permissions(item, rule)
Delete default workbook permissions.
REST API: Delete Default Workbook Permissions
Parameters
| Name |
Description |
item |
A project object. |
rule |
A PermissionsRule object. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
capabilities = {
TSC.Permission.Capability.ViewComments: TSC.Permission.Mode.Allow
}
rule = TSC.PermissionsRule(
grantee=project_item,
capabilities=capabilities
)
server.projects.delete_workbook_default_permissions(project_item, rule)
projects.delete_datasource_default_permissions
projects.delete_datasource_default_permissions(item, rule)
Delete default datasource permissions.
REST API: Delete Default Datasource Permissions
Parameters
| Name |
Description |
item |
A project object. |
rule |
A PermissionsRule object. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
capabilities = {
TSC.Permission.Capability.ExportXml: TSC.Permission.Mode.Allow
}
rule = TSC.PermissionsRule(
grantee=project_item,
capabilities=capabilities
)
server.projects.delete_datasource_default_permissions(project_item, rule)
projects.delete_flow_default_permissions
projects.delete_flow_default_permissions(item, rule)
Delete default flow permissions.
REST API: Delete Default Flow Permissions
Parameters
| Name |
Description |
item |
A project object. |
rule |
A PermissionsRule object. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
all_project_items, pagination_item = server.projects.get()
project_item = all_project_items[0]
capabilities = {
TSC.Permission.Capability.Read: TSC.Permission.Mode.Allow
}
rule = TSC.PermissionsRule(
grantee=project_item,
capabilities=capabilities
)
server.projects.delete_flow_default_permissions(project_item, rule)
Requests
The TSC library provides a RequestOptions class that you can use to filter results returned from the server.
You can use the Sort and RequestOptions classes to filter and sort the following endpoints:
- Users
- Datasources
- Groups
- Workbooks
- Views
You can use the ImageRequestOptions and PDFRequestOptions to set options for views returned as images and PDF files.
Note: View filters set via vf() on CSVRequestOptions, ImageRequestOptions, or PDFRequestOptions apply exact-match only. Operators like greater-than, less-than, contains, or value ranges are not supported by the underlying REST endpoint. See the Tableau REST API filtering documentation for the server-side detail. If you need range filtering for exports, expose the range bounds as workbook parameters and use .parameter() to set them.
For more information about filtering and sorting, see Filter and Sort.
RequestOptions class
RequestOptions(pagenumber=1, pagesize=100)
Attributes
| Name |
Description |
pagenumber |
The page number of the returned results. The default value is 1. |
pagesize |
The number of items to return with each page (the default value is 100). |
sort() |
Returns a iterable set of Sort objects. |
filter() |
Returns an iterable set of Filter objects. |
RequestOptions.Field class
The RequestOptions.Field class corresponds to the fields used in filter expressions in the Tableau REST API. For more information, see Filtering and Sorting in the Tableau REST API.
Attributes
Attributes
| Field |
Description |
CreatedAt |
Same as ‘createdAt’ in the REST API. TSC. RequestOptions.Field.CreatedAt |
LastLogin |
Same as ‘lastLogin’ in the REST API. RequestOptions.Field.LastLogin |
Name |
Same as ‘name’ in the REST API. RequestOptions.Field.Name |
OwnerName |
Same as ‘ownerName’ in the REST API. RequestOptions.Field.OwnerName |
SiteRole |
Same as ‘siteRole’ in the REST API. RequestOptions.Field.SiteRole |
Tags |
Same as ‘tags’ in the REST API. RequestOptions.Field.Tags |
UpdatedAt |
Same as ‘updatedAt’ in the REST API. RequestOptions.Field.UpdatedAt |
RequestOptions.Operator class
Specifies the operators you can use to filter requests.
Attributes
| Operator |
Description |
Equals |
Sets the operator to equals (same as eq in the REST API). TSC.RequestOptions.Operator.Equals |
GreaterThan |
Sets the operator to greater than (same as gt in the REST API). TSC.RequestOptions.Operator.GreaterThan |
GreaterThanOrEqual |
Sets the operator to greater than or equal (same as gte in the REST API). TSC.RequestOptions.Operator.GreaterThanOrEqual |
LessThan |
Sets the operator to less than (same as lt in the REST API). TSC.RequestOptions.Operator.LessThan |
LessThanOrEqual |
Sets the operator to less than or equal (same as lte in the REST API). TSC.RequestOptions.Operator.LessThanOrEqual |
In |
Sets the operator to in (same as in in the REST API). TSC.RequestOptions.Operator.In |
RequestOptions.Direction class
Specifies the direction to sort the returned fields.
Attributes
| Name |
Description |
Asc |
Sets the sort direction to ascending (TSC.RequestOptions.Direction.Asc) |
Desc |
Sets the sort direction to descending (TSC.RequestOptions.Direction.Desc). |
CSVRequestOptions class
CSVRequestOptions(maxage=-1)
Use this class to specify view filters to be applied when the CSV data is generated. Optionally, you can specify the maximum age of the CSV data cached on the server by providing a maxage value. See views.populate_csv.
Attributes
| Name |
Description |
maxage |
Optional. The maximum number of minutes the CSV data will be cached on the server before being refreshed. The value must be an integer between 1 and 240 minutes. 0 will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, maxage is set to -1, indicating the default behavior configured in server settings. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set view filters
csv_req_option = TSC.CSVRequestOptions(maxage=5)
csv_req_option.vf('Region', 'South')
csv_req_option.vf('Category', 'Furniture')
# retrieve the csv data for the view
server.views.populate_csv(view_item, csv_req_option)
If you set a parameter in the workbook, you can also pass the parameter value as part of the CSVRequestOptions object. For example, if you have a parameter named Region in the workbook, you can set the parameter value to South as follows:
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set view filters
csv_req_option = TSC.CSVRequestOptions(maxage=5)
csv_req_option.parameter('Region', 'South')
# retrieve the csv data for the view
server.views.populate_csv(view_item, csv_req_option)
ExcelRequestOptions class
ExcelRequestOptions(maxage=-1)
Use this class to specify view filters to be applied when data is generated in an Excel file format. Optionally, you can specify the maximum age of the Excel data cached on the server by providing a maxage value. See views.populate_csv.
Attributes
| Name |
Description |
maxage |
Optional. The maximum number of minutes the Excel data will be cached on the server before being refreshed. The value must be an integer between 1 and 240 minutes. 0 will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, maxage is set to -1, indicating the default behavior configured in server settings. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set view filters
excel_req_option = TSC.ExcelRequestOptions(maxage=5)
excel_req_option.vf('Region', 'South')
excel_req_option.vf('Category', 'Furniture')
# retrieve the excel data for the view
server.views.populate_excel(view_item, excel_req_option)
If you set a parameter in the workbook, you can also pass the parameter value as part of the ExcelRequestOptions object. For example, if you have a parameter named Region in the workbook, you can set the parameter value to South as follows:
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set view filters
excel_req_option = TSC.ExcelRequestOptions(maxage=5)
excel_req_option.parameter('Region', 'South')
# retrieve the excel data for the view
server.views.populate_excel(view_item, excel_req_option)
ImageRequestOptions class
ImageRequestOptions(imageresolution=None, maxage=-1)
Use this class to specify the resolution of the view and, optionally, the maximum age of the image cached on the server. You can also use this class to specify view filters to be applied when the image is generated. See views.populate_image.
Attributes
| Name |
Description |
imageresolution |
The resolution of the view returned as an image. If unspecified, the views.populate_image method returns an image with standard resolution (the width of the returned image is 784 pixels). If you set this parameter value to high (Resolution.High), the width of the returned image is 1568 pixels. For both resolutions, the height varies to preserve the aspect ratio of the view. |
maxage |
Optional. The maximum number of minutes the image will be cached on the server before being refreshed. The value must be an integer between 1 and 240 minutes. 0 will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, maxage is set to -1, indicating the default behavior configured in server settings. |
View Filters
You can use the vf('filter_name', 'filter_value') method to add view filters. When the image is generated, the specified filters will be applied to the view.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set the image request option
image_req_option = TSC.ImageRequestOptions(imageresolution=TSC.ImageRequestOptions.Resolution.High, maxage=1)
# (optional) set a view filter
image_req_option.vf('Category', 'Furniture')
# retrieve the image for the view
server.views.populate_image(view_item, image_req_option)
If you set a parameter in the workbook, you can also pass the parameter value as part of the ImageRequestOptions object. For example, if you have a parameter named Region in the workbook, you can set the parameter value to South as follows:
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set view filters
image_req_option = TSC.ImageRequestOptions(maxage=5)
image_req_option.parameter('Region', 'South')
# retrieve the image data for the view
server.views.populate_image(view_item, image_req_option)
PDFRequestOptions class
PDFRequestOptions(page_type=None, orientation=None, maxage=-1)
Use this class to specify the format of the PDF that is returned for the view. Optionally, you can specify the maximum age of the rendered PDF that is cached on the server by providing a maxage value. See views.populate_pdf.
Attributes
| Name |
Description |
page_type |
The type of page returned in PDF format for the view. The page_type is set using the PageType class:
PageType.A3
PageType.A4
PageType.A5
PageType.B5
PageType.Executive
PageType.Folio
PageType.Ledger
PageType.Legal
PageType.Letter
PageType.Note
PageType.Quarto
PageType.Tabloid
PageType.Unspecified |
orientation |
The orientation of the page. The options are portrait and landscape. The options are set using the Orientation class:
Orientation.Portrait
Orientation.Landscape |
maxage |
Optional. The maximum number of minutes the rendered PDF will be cached on the server before being refreshed. The value must be an integer between 1 and 240 minutes. 0 will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, maxage is set to -1, indicating the default behavior configured in server settings. |
viz_height |
Optional. The height of the output PDF in pixels. If specified, viz_width must also be specified. |
viz_width |
Optional. The width of the output PDF in pixels. If specified, viz_height must also be specified. |
View Filters
You can use the vf('filter_name', 'filter_value') method to add view filters. When the PDF is generated, the specified filters will be applied to the view.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set the PDF request options
pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4,
orientation=TSC.PDFRequestOptions.Orientation.Landscape,
maxage=1)
# (optional) set a view filter
pdf_req_option.vf('Region', 'West')
# retrieve the PDF for a view
server.views.populate_pdf(view_item, pdf_req_option)
You can also specify height and width for the visualization to be rendered in the PDF. If you specify the height and width, you must specify both values. The height and width are set in pixels.
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set the PDF request options
pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4,
orientation=TSC.PDFRequestOptions.Orientation.Landscape,
maxage=1,
viz_height=800,
viz_width=1200)
server.views.populate_pdf(view_item, pdf_req_option)
If you set a parameter in the workbook, you can also pass the parameter value as part of the PDFRequestOptions object. For example, if you have a parameter named Region in the workbook, you can set the parameter value to South as follows:
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, get a specific view, etc.
# set view filters
pdf_req_option = TSC.PDFRequestOptions(maxage=5)
pdf_req_option.parameter('Region', 'South')
# retrieve the pdf data for the view
server.views.populate_pdf(view_item, pdf_req_option)
Schedules
Using the TSC library, you can schedule extract refresh or subscription tasks on Tableau Server. You can also get and update information about the scheduled tasks, or delete scheduled tasks.
If you have the identifier of the job, you can use the TSC library to find out the status of the asynchronous job.
The schedule properties are defined in the ScheduleItem class. The class corresponds to the properties for schedules you can access in Tableau Server or by using the Tableau Server REST API. The Schedule methods are based upon the endpoints for jobs in the REST API and operate on the JobItem class.
ScheduleItem class
ScheduleItem(name, priority, schedule_type, execution_order, interval_item)
The ScheduleItem class contains information about the specified schedule running on Tableau Server. The ScheduleItem class defines the information you can query and set. The class members correspond to the attributes of a server response payload.
Source file: models/schedule_item.py
Attributes
| Name |
Description |
name |
The name of the schedule. |
priority |
The priority of the schedule (integer). Lower values represent higher priorities, with 0 indicating the highest priority. |
schedule_type |
The type of task. The types are either an Extract for an extract refresh task or a Subscription for a scheduled subscription. |
execution_order |
Specifies how the scheduled task should run. The choices are Parallelwhich uses all available background processes for this scheduled task, or Serial, which limits this schedule to one background process. |
interval_item |
Specifies the frequency that the scheduled task should run. The interval_item is an instance of the IntervalItem class. The interval_item has properties for frequency (hourly, daily, weekly, monthly), and what time and date the scheduled item runs. You set this value by declaring an IntervalItem object that is one of the following: HourlyInterval, DailyInterval, WeeklyInterval, or MonthlyInterval. |
IntervalItem class
This class sets the frequency and start time of the scheduled item. This class contains the classes for the hourly, daily, weekly, and monthly intervals. This class mirrors the options you can set using the REST API and the Tableau Server interface.
Attributes
| Name |
Description |
HourlyInterval |
Runs scheduled item hourly. To set the hourly interval, you create an instance of the HourlyInterval class and assign the following values: start_time, end_time, and interval_value. To set the start_time and end_time, assign the time value using this syntax: start_time=time(hour, minute) and end_time=time(hour, minute). The hour is specified in 24 hour time. The interval_value specifies how often the to run the task within the start and end time. The options are expressed in hours. For example, interval_value=.25 is every 15 minutes. The values are .25, .5, 1, 2, 4, 6, 8, 12. Hourly schedules that run more frequently than every 60 minutes must have start and end times that are on the hour. |
DailyInterval |
Runs the scheduled item daily. To set the daily interval, you create an instance of the DailyInterval and assign the start_time. The start time uses the syntax start_time=time(hour, minute). |
WeeklyInterval |
Runs the scheduled item once a week. To set the weekly interval, you create an instance of the WeeklyInterval and assign the start time and multiple instances for the interval_value (days of week and start time). The start time uses the syntax time(hour, minute). The interval_value is the day of the week, expressed as a IntervalItem. For example TSC.IntervalItem.Day.Monday for Monday. |
MonthlyInterval |
Runs the scheduled item once a month. To set the monthly interval, you create an instance of the MonthlyInterval and assign the start time and day. The |
Schedule methods
The schedule methods are based upon the endpoints for schedules in the REST API and operate on the ScheduleItem class.
Source files: server/endpoint/schedules_endpoint.py
schedules.add_to_schedule
schedules.add_to_schedule(schedule_id, workbook=None, datasource=None, flow=None, task_type=None)
Adds a DatasourceItem, FlowItem, or WorkbookItem to a schedule.
REST API: Add Data Source to Schedule
Parameters
| Name |
Description |
schedule_id |
The identifier (id) of the schedule to add the data source or workbook to. Can be retrieved from a ScheduleItem, e.g., by performing schedules.get(). |
workbook |
(Optional) A WorkbookItem that should be added to the schedule. Only provide either workbook or datasource, passing multiple items will be deprecated. |
datasource |
(Optional) A DatasourceItem that should be added to the schedule. Only provide either workbook or datasource, passing multiple items will be deprecated. |
flow |
(Optional) A FlowItem that should be added to the schedule. Only applicable if workbook = None and datasource = None. |
task_type |
(Optional) Determines the type of task. One of TaskItem.Type: ExtractRefresh, DataAcceleration, RunFlow. |
Returns
Returns a List of AddResponses.
Example
import tableauserverclient as TSC
# sign in, etc.
# get a datasource item that should be added to a schedule
datasource_item = server.datasources.get("d14dd951-01c1-4879-8bc2-e96d7dec9f0")
# retrieve the id of the target schedule
schedule_id = schedule_item.id # can be a freshly created schedule or one queried via `schedules.get()`
# Add the data source to the schedule
server.schedules.add_to_schedule(
schedule_id=schedule_id,
datasource=datasource_item,
)
schedules.create
schedules.create(schedule_item)
Creates a new schedule for an extract refresh or a subscription.
REST API: Create Schedule
Parameters
| Name |
Description |
schedule_item |
The settings for the schedule that you want to create. You need to create an instance of ScheduleItem and pass it to the create method. The ScheduleItem includes the IntervalItem which specifies the frequency, or interval, that the schedule should run. |
Returns
Returns a new instance of schedule_item.
Exceptions
| Error |
Description |
Interval item must be defined. |
Raises an exception if the schedule_item.interval_item is not specified. The interval item specifies whether the interval is hourly, daily, weekly, or monthly. |
Example
import tableauserverclient as TSC
from datetime import time
# sign in, etc.
# Create an interval to run every 2 hours between 2:30AM and 11:00PM
hourly_interval = TSC.HourlyInterval(start_time=time(2, 30),
end_time=time(23, 0),
interval_value=2)
# Create schedule item
hourly_schedule = TSC.ScheduleItem("Hourly-Schedule",
50,
TSC.ScheduleItem.Type.Extract,
TSC.ScheduleItem.ExecutionOrder.Parallel,
hourly_interval)
# Create schedule
hourly_schedule = server.schedules.create(hourly_schedule)
schedules.delete
schedules.delete(schedule_id)
Deletes an existing schedule for an extract refresh or a subscription.
REST API: Delete Schedule
Parameters
| Name |
Description |
schedule_id |
The identifier (schedule_item.id) of the schedule to delete. Use the schedule.get() method to get the identifiers of the schedules on the server. |
Returns
None.
Exceptions
| Error |
Description |
Schedule ID undefined |
The identifier is not a valid identifier for a schedule on the server. |
schedules.get
Returns all schedule items from the server.
REST API: Query Schedules
schedules.get_by_id
schedules.get_by_id(schedule_id)
Returns the specified schedule.
REST API: Get Schedule
Parameters
| Name |
Description |
req_options |
(Optional) Additional request options to send to the endpoint. |
schedules.update
schedules.update(schedule_item)
Parameters
| Name |
Description |
schedule_item |
The settings for the schedule that you want to update. You need to fetch an existing instance of ScheduleItem from the get method, make your changes, and then pass it to the update method to update the schedule on the server. The ScheduleItem includes the IntervalItem which specifies the frequency, or interval, that the schedule should run. |
REST API: Update Schedules
Hourly schedule example
import tableauserverclient as TSC
from datetime import time
# sign in, etc.
# Create an interval to run every 2 hours between 2:30AM and 11:00PM
hourly_interval = TSC.HourlyInterval(start_time=time(2, 30),
end_time=time(23, 0),
interval_value=2)
# Create schedule item
hourly_schedule = TSC.ScheduleItem("Hourly-Schedule",
50,
TSC.ScheduleItem.Type.Extract,
TSC.ScheduleItem.ExecutionOrder.Parallel,
hourly_interval)
# Create schedule
hourly_schedule = server.schedules.create(hourly_schedule)
Daily schedule example
import tableauserverclient as TSC
from datetime import time
# sign in, etc.
# Create a daily interval to run every day at 12:30AM
daily_interval = TSC.DailyInterval(start_time=time(0, 30))
# Create schedule item using daily interval
daily_schedule = TSC.ScheduleItem("Daily-Schedule",
60,
TSC.ScheduleItem.Type.Subscription,
TSC.ScheduleItem.ExecutionOrder.Serial,
daily_interval)
# Create daily schedule
daily_schedule = server.schedules.create(daily_schedule)
Weekly schedule example
import tableauserverclient as TSC
from datetime import time
# sign in, etc.
# Create a weekly interval to run every Monday, Wednesday, and Friday at 7:15PM
weekly_interval = TSC.WeeklyInterval(time(19, 15),
TSC.IntervalItem.Day.Monday,
TSC.IntervalItem.Day.Wednesday,
TSC.IntervalItem.Day.Friday)
# Create schedule item using weekly interval
weekly_schedule = TSC.ScheduleItem("Weekly-Schedule", 70,
TSC.ScheduleItem.Type.Extract,
TSC.ScheduleItem.ExecutionOrder.Serial,
weekly_interval)
# Create weekly schedule
weekly_schedule = server.schedules.create(weekly_schedule)
Monthly schedule example
import tableauserverclient as TSC
from datetime import time
# sign in, etc.
# Create a monthly interval to run on the 15th of every month at 11:30PM
monthly_interval = TSC.MonthlyInterval(start_time=time(23, 30),
interval_value=15)
# Create schedule item using monthly interval
monthly_schedule = TSC.ScheduleItem("Monthly-Schedule",
80,
TSC.ScheduleItem.Type.Subscription
TSC.ScheduleItem.ExecutionOrder.Parallel, monthly_interval)
# Create monthly schedule
monthly_schedule = server.schedules.create(monthly_schedule)
schedules.batch_update_state
schedules.batch_update_state(schedules, state, update_all=False)
Batch update the status of one or more schedules. If update_all is set to True, all schedules on the Tableau Server are affected.
REST API: Batch Update Schedule State
Version
This endpoint is available with REST API version 3.27 and up.
Parameters
| Name |
Description |
schedules |
(Optional) An iterable of ScheduleItem objects or schedule ID strings to be updated. If update_all=True, this parameter is ignored. |
state |
The state to set for the schedules. Must be either "active" or "suspended". |
update_all |
(Optional) If set to True, applies the state to all schedules on the server. Defaults to False. |
Returns
A list of strings containing the IDs of the affected schedules.
Example
import tableauserverclient as TSC
# sign in, etc.
# Get schedules to update
schedules, pagination = server.schedules.get()
schedules_to_update = [schedules[0], schedules[1], schedules[2]]
# Batch update schedules to active state
affected_ids = server.schedules.batch_update_state(schedules_to_update, "active")
# Or update using schedule ID strings
schedule_ids = ["593d2ebf-0d18-4deb-9d21-b113a4902583",
"cecbb71e-def0-4030-8068-5ae50f51db1c"]
affected_ids = server.schedules.batch_update_state(schedule_ids, "suspended")
# Update all schedules on the server
all_affected_ids = server.schedules.batch_update_state([], "active", update_all=True)
Server
In the Tableau REST API, the server (https://MY-SERVER/) is the base or core of the URI that makes up the various endpoints or methods for accessing resources on the server (views, workbooks, sites, users, data sources, etc.)
The TSC library provides a Server class that represents the server. You create a server instance to sign in to the server and to call the various methods for accessing resources.
Server class
The Server class contains the attributes that represent the server on Tableau Server. After you create an instance of the Server class, you can sign in to the server and call methods to access all of the resources on the server.
Attributes
| Attribute |
Description |
server_address |
Specifies the address of the Tableau Server or Tableau Cloud (for example, https://MY-SERVER/). |
version |
Specifies the version of the REST API to use (for example, '2.5'). When you use the TSC library to call methods that access Tableau Server, the version is passed to the endpoint as part of the URI (https://MY-SERVER/api/2.5/). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of version is set to '2.3', which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see REST API Versions. |
Example
import tableauserverclient as TSC
# create a instance of server
server = TSC.Server('https://MY-SERVER')
# sign in, etc.
# change the REST API version to match the server
server.use_server_version()
# or change the REST API version to match a specific version
# for example, 2.8
# server.version = '2.8'
Server.Resources
When you create an instance of the Server class, you have access to the resources on the server after you sign in. You can select these resources and their methods as members of the class, for example: server.views.get()
| Resource |
Description |
| server.auth |
Sets authentication for sign in and sign out. See Auth |
| server.views |
Access the server views and methods. See Views |
| server.users |
Access the user resources and methods. See Users |
| server.sites |
Access the sites. See Sites |
| server.groups |
Access the groups resources and methods. See Groups |
| server.jobs |
Access the jobs resources and methods. See Jobs |
| server.workbooks |
Access the resources and methods for workbooks. See Workbooks |
| server.datasources |
Access the resources and methods for data sources. See Data Sources |
| server.projects |
Access the resources and methods for projects. See Projects |
| server.schedules |
Access the resources and methods for schedules. See Schedules |
| server.subscriptions |
Access the resources and methods for subscriptions. See Subscriptions |
| server.server_info |
Access the resources and methods for server information. See ServerInfo class |
Server.PublishMode
The Server class has PublishMode class that enumerates the options that specify what happens when you publish a workbook or data source. The options are Overwrite, Append, or CreateNew.
Properties
| Resource |
Description |
PublishMode.Overwrite |
Overwrites the workbook or data source. |
PublishMode.Append |
Appends to the workbook or data source. |
PublishMode.CreateNew |
Creates a new workbook or data source. |
Example
import tableauserverclient as TSC
# login, etc.
print(TSC.Server.PublishMode.Overwrite)
# prints 'Overwrite'
overwrite_true = TSC.Server.PublishMode.Overwrite
...
# pass the PublishMode to the publish workbooks method
new_workbook = server.workbooks.publish(new_workbook, args.filepath, overwrite_true)
ServerInfoItem class
ServerInfoItem(product_version, build_number, rest_api_version)
The ServerInfoItem class contains the build and version information for Tableau Server. The server information is accessed with the server_info.get() method, which returns an instance of the ServerInfo class.
Attributes
| Name |
Description |
product_version |
Shows the version of the Tableau Server or Tableau Cloud (for example, 10.2.0). |
build_number |
Shows the specific build number (for example, 10200.17.0329.1446). |
rest_api_version |
Shows the supported REST API version number. Note that this might be different from the default value specified for the server, with the Server.version attribute. To take advantage of new features, you should query the server and set the Server.version to match the supported REST API version number. |
ServerInfo methods
The TSC library provides a method to access the build and version information from Tableau Server.
server_info.get
Retrieve the build and version information for the server.
This method makes an unauthenticated call, so no sign in or authentication token is required.
REST API: Server Info
Parameters
None
Exceptions
| Error |
Description |
404003 UNKNOWN_RESOURCE |
Raises an exception if the server info endpoint is not found. |
Example
import tableauserverclient as TSC
# create a instance of server
server = TSC.Server('https://MY-SERVER')
# set the version number > 2.3
# the server_info.get() method works in 2.4 and later
server.version = '2.5'
s_info = server.server_info.get()
print("\nServer info:")
print("\tProduct version: {0}".format(s_info.product_version))
print("\tREST API version: {0}".format(s_info.rest_api_version))
print("\tBuild number: {0}".format(s_info.build_number))
Sites
Using the TSC library, you can query a site or sites on a server, or create or delete a site on the server.
The site resources for Tableau Server and Tableau Cloud are defined in the SiteItem class. The class corresponds to the site resources you can access using the Tableau Server REST API. The site methods are based upon the endpoints for sites in the REST API and operate on the SiteItem class.
SiteItem class
SiteItem(name, content_url, admin_mode=None, user_quota=None, storage_quota=None,
disable_subscriptions=False, subscribe_others_enabled=True, revision_history_enabled=False)
The SiteItem class contains the members or attributes for the site resources on Tableau Server or Tableau Cloud. The SiteItem class defines the information you can request or query from Tableau Server or Tableau Cloud. The class members correspond to the attributes of a server request or response payload.
Attributes
| Attribute |
Description |
name |
The name of the site. The name of the default site is “”. |
content_url |
The path to the site. |
admin_mode |
(Optional) For Tableau Server only. Specify ContentAndUsers to allow site administrators to use the server interface and tabcmd commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify ContentOnly to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.) |
user_quota |
(Optional) Specifies the total number of users for the site. The number can’t exceed the number of licenses activated for the site; and if tiered capacity attributes are set, then user_quota will equal the sum of the tiered capacity values, and attempting to set user_quota will cause an error. |
Tiered capacity attributes: tier_explorer_capacity tier_creator_capacity tier_viewer_capacity |
(Optional) The maximum number of licenses for users with the Creator, Explorer, or Viewer role, respectively, allowed on a site. |
storage_quota |
(Optional) Specifies the maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again. |
disable_subscriptions |
(Optional) Specify true to prevent users from being able to subscribe to workbooks on the specified site. The default is false. |
subscribe_others_enabled |
(Optional) Specify false to prevent server administrators, site administrators, and project or content owners from being able to subscribe other users to workbooks on the specified site. The default is true. |
revision_history_enabled |
(Optional) Specify true to enable revision history for content resources (workbooks and datasources). The default is false. |
revision_limit |
(Optional) Specifies the number of revisions of a content source (workbook or data source) to allow. On Tableau Server, the default is 25. |
state |
Shows the current state of the site (Active or Suspended). |
Example
# create a new instance of a SiteItem
new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode='ContentAndUsers', user_quota=15, storage_quota=1000, disable_subscriptions=True)
Source file: models/site_item.py
SiteAuthConfiguration class
The SiteAuthConfiguration class contains the attributes for the authentication configuration on Tableau Cloud. This class represents the authentication configuration information returned when using the sites.list_auth_configurations method.
Attributes
| Attribute |
Description |
auth_setting |
The authentication type (e.g., SAML, OpenID, TableauIDWithMFA). |
enabled |
Boolean value indicating whether the authentication configuration is enabled. |
idp_configuration_id |
The unique identifier for the authentication configuration. |
idp_configuration_name |
The name of the authentication configuration. |
known_provider_alias |
The provider name for the authentication method in case of OpenID configuration. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
# Get authentication configurations for the current site
auth_configs = server.sites.list_auth_configurations()
# Display configuration details
for config in auth_configs:
print(f"ID: {config.idp_configuration_id}")
print(f"Name: {config.idp_configuration_name}")
print(f"Type: {config.auth_setting}")
print(f"Enabled: {config.enabled}")
print(f"Provider: {config.known_provider_alias}")
Site methods
The TSC library provides methods that operate on sites for Tableau Server and Tableau Cloud. These methods correspond to endpoints or methods for sites in the Tableau REST API.
Source file: server/endpoint/sites_endpoint.py
sites.create
Creates a new site on the server for the specified site item object.
Tableau Server only.
REST API: Create Site
Parameters
| Name |
Description |
site_item |
The settings for the site that you want to create. You need to create an instance of SiteItem and pass it to the create method. |
Returns
Returns a new instance of SiteItem.
Example
import tableauserverclient as TSC
# create an instance of server
server = TSC.Server('https://MY-SERVER')
# create shortcut for admin mode
content_users=TSC.SiteItem.AdminMode.ContentAndUsers
# create a new SiteItem
new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode=content_users, user_quota=15, storage_quota=1000, disable_subscriptions=True)
# call the sites create method with the SiteItem
new_site = server.sites.create(new_site)
sites.get
Queries all the sites on the server.
REST API: Query Sites
Parameters
None.
Returns
Returns a list of all SiteItem objects and a PaginationItem. Use these values to iterate through the results.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
# query the sites
all_sites, pagination_item = server.sites.get()
# print all the site names and ids
for site in all_sites:
print(site.id, site.name, site.content_url, site.state)
sites.get_by_id
Queries the site with the given ID.
REST API: Query Site
Parameters
| Name |
Description |
site_id |
The id for the site you want to query. |
Exceptions
| Error |
Description |
Site ID undefined. |
Raises an error if an id is not specified. |
Returns
Returns the SiteItem.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
a_site = server.sites.get_by_id('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')
print("\nThe site with id '9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d' is: {0}".format(a_site.name))
sites.get_by_name
sites.get_by_name(site_name)
Queries the site with the specified name.
REST API: Query Site
Parameters
| Name |
Description |
site_name |
The name of the site you want to query. |
Exceptions
| Error |
Description |
Site Name undefined. |
Raises an error if an name is not specified. |
Returns
Returns the SiteItem.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
a_site = server.sites.get_by_name('MY_SITE')
sites.update
Modifies the settings for site.
The site item object must include the site ID and overrides all other settings.
REST API: Update Site
Parameters
| Name |
Description |
site_item |
The site item that you want to update. The settings specified in the site item override the current site settings. |
Exceptions
| Error |
Description |
Site item missing ID. |
The site id must be present and must match the id of the site you are updating. |
You cannot set admin_mode to ContentOnly and also set a user quota |
To set the user_quota, the AdminMode must be set to ContentAndUsers |
Returns
Returns the updated site_item.
Example
...
# make some updates to an existing site_item
site_item.name ="New name"
# call update
site_item = server.sites.update(site_item)
...
sites.delete
Deletes the specified site.
REST API: Delete Site
Parameters
| Name |
Description |
site_id |
The id of the site that you want to delete. |
Exceptions
| Error |
Description |
Site ID Undefined. |
The site id must be present and must match the id of the site you are deleting. |
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
server.sites.delete('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')
sites.list_auth_configurations
sites.list_auth_configurations()
Lists the authentication configurations for the current site.
REST API: List Authentication Configurations for the current Site
Returns
Returns a list of authentication configurations for the current site.
Example
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
auth_configs = server.sites.list_auth_configurations()
for config in auth_configs:
print(f"IDP Configuration ID: {config.idp_configuration_id}")
print(f"Name: {config.idp_configuration_name}")
print(f"Type: {config.auth_setting}")
print(f"Enabled: {config.enabled}")
sites.get_by_content_url
sites.get_by_content_url(content_url)
Returns the site with the specified content URL.
REST API: Query Site
Parameters
| Name |
Description |
content_url |
The content_url for the site to query. This is the contentUrl value in the REST API and corresponds to the portion of the URL after /site/ (for example, "MarketingTeam"). Use an empty string for the default site. |
Returns
Returns a SiteItem.
Version
Version 2.0 and later. See REST API versions.
Example
site = server.sites.get_by_content_url('MarketingTeam')
print(site.id, site.name)
sites.encrypt_extracts
sites.encrypt_extracts(site_id)
Encrypts all extracts on the specified site.
REST API: Encrypt Extracts
Parameters
| Name |
Description |
site_id |
The identifier (id) for the site on which to encrypt all extracts. |
Version
Version 3.5 and later. See REST API versions.
Example
server.sites.encrypt_extracts(server.site_id)
sites.decrypt_extracts
sites.decrypt_extracts(site_id)
Decrypts all extracts on the specified site.
REST API: Decrypt Extracts
Parameters
| Name |
Description |
site_id |
The identifier (id) for the site on which to decrypt all extracts. |
Version
Version 3.5 and later. See REST API versions.
Example
server.sites.decrypt_extracts(server.site_id)
sites.re_encrypt_extracts
sites.re_encrypt_extracts(site_id)
Re-encrypts all extracts on the specified site using new encryption keys.
REST API: Reencrypt Extracts
Parameters
| Name |
Description |
site_id |
The identifier (id) for the site on which to re-encrypt all extracts. |
Version
Version 3.5 and later. See REST API versions.
Example
server.sites.re_encrypt_extracts(server.site_id)
Sort
The Sort class is used with request options (RequestOptions) where you can filter and sort on the results returned from the server.
You can use the sort and request options to filter and sort the following endpoints:
- Users
- Datasources
- Workbooks
- Views
Sort class
Attributes
| Name |
Description |
field |
Sets the field to sort on. The fields are defined in the RequestOption class. |
direction |
The direction to sort, either ascending (Asc) or descending (Desc). The options are defined in the RequestOptions.Direction class. |
Example
# create a new instance of a request option object
req_option = TSC.RequestOptions()
# add the sort expression, sorting by name and direction
req_option.sort.add(TSC.Sort(TSC.RequestOptions.Field.Name,
TSC.RequestOptions.Direction.Asc))
matching_workbooks, pagination_item = server.workbooks.get(req_option)
for wb in matching_workbooks:
print(wb.name)
For information about using the Sort class, see Filter and Sort.
Subscriptions
Using the TSC library, you can manage subscriptions to views or workbooks on a site. You can get information about all the subscriptions on a site, or information about a specific subscription on a site, and you can create, update, or delete subscriptions.
SubscriptionItem class
The subscription resources for Tableau Server are defined in the SubscriptionItem class. The class corresponds to the subscription resources you can access using the Tableau Server REST API. The subscription methods are based upon the endpoints for subscriptions in the REST API and operate on the SubscriptionItem class.
SubscriptionItem(subject, schedule_id, user_id, target)
Attributes
| Name |
Description |
id |
The id of the subscription on the site. |
attach_image |
Setting this to True will cause the subscriber to receive mail with .png images of workbooks or views attached to it. By default, this value is set to True. If attach_pdf is set to False, then this value cannot be set to False. |
attach_pdf |
Setting this to True will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. By default, this value is set to False. |
message |
The text body of the subscription email message. |
page_orientation |
The orientation of the pages produced when attach_pdf is True. If this parameter is not present the page orientation will default to Portrait. See chart below for a full list of values. |
page_size_option |
The type of page produced, which determines the page dimensions when attach_pdf is True. If this parameter is not present the page type will default to Letter. See chart below for a full list of values. |
schedule_id |
The id of the schedule associated with the specific subscription. |
send_if_view_empty |
Applies to views only (see target attribute). If True, an image is sent even if the view specified in a subscription is empty. If False, nothing is sent if the view is empty. The default value is True. |
subject |
The subject of the subscription. This is the description that you provide to identify the subscription. |
suspended |
Setting this value to True stops email delivery for the specified subscription. Setting it to False will resume email delivery for the subscription. |
target |
The target of the subscription, that is, the content that is subscribed to (view, workbook). The target is an instance of the target class. The target has two properties, the id of the workbook or view (target.id), and the type (target.type), which can either view or workbook. The send_if_view_empty attribute can only be set to True if the target.type is set to View. |
user_id |
The identifier of the user (person) who receives the subscription. |
Valid PDF options (applies only if attach_pdf is set to True)
| Attribute |
Valid options |
page_orientation |
TSC.PDFRequestOptions.Orientation.Landscape
TSC.PDFRequestOptions.Orientation.Portrait |
page_size_option |
TSC.PDFRequestOptions.PageType.A3
TSC.PDFRequestOptions.PageType.A4
TSC.PDFRequestOptions.PageType.A5
TSC.PDFRequestOptions.PageType.B5
TSC.PDFRequestOptions.PageType.Executive
TSC.PDFRequestOptions.PageType.Folio
TSC.PDFRequestOptions.PageType.Ledger
TSC.PDFRequestOptions.PageType.Legal
TSC.PDFRequestOptions.PageType.Letter
TSC.PDFRequestOptions.PageType.Note
TSC.PDFRequestOptions.PageType.Quarto
TSC.PDFRequestOptions.PageType.Tabloid |
Source files:
server/endpoints/subscription_item.py
server/request_options.py
Subscription methods
The Tableau Server Client provides several methods for interacting with subscription resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
Source files: server/endpoints/subscriptions_endpoint.py
subscriptions.create
subscriptions.create(subscription_item)
Creates a subscription to a view or workbook for a specific user on a specific schedule.
When a user is subscribed to the content, Tableau Server sends the content to the user in email on the schedule that’s defined on Tableau Server and specified in the subscription_item.
To create a new subscription you need to first create a new subscription_item (from SubscriptionItem class).
REST API: Create Subscription
Parameters
| Name |
Description |
subscription_item |
Specifies the user to subscribe, the content to subscribe to, the schedule to associate the subscription with, and other metadata for the subscription. |
Returns
Returns the new SubscriptionItem object.
Example
# Create the target (content) of the subscription with its ID and type.
# ID can be obtained by calling workbooks.get() or views.get().
target = TSC.Target('c7a9327e-1cda-4504-b026-ddb43b976d1d', 'workbook')
# Store the schedule ID and user ID.
# IDs can be obtained by calling schedules.get() and users.get().
schedule_id = 'b60b4efd-a6f7-4599-beb3-cb677e7abac1'
user_id = '28ce5884-ed38-49a9-aa10-8f5fbd59bbf6'
# Create the new SubscriptionItem object with variables from above.
new_sub = TSC.SubscriptionItem('My Subscription', schedule_id, user_id, target)
# (Optional) Set other fields. Any of these can be added or removed.
new_sub.attach_image = False
new_sub.attach_pdf = True
new_sub.message = "You have an alert!"
new_sub.page_orientation = TSC.PDFRequestOptions.Orientation.Landscape
new_sub.page_size_option = TSC.PDFRequestOptions.PageType.B4
new_sub.send_if_view_empty = True
# Create the new subscription on the site you are logged in.
new_sub = server.subscriptions.create(new_sub)
print(new_sub.subject)
subscriptions.delete
subscriptions.delete(subscription_id)
Deletes the specified subscription from the site.
REST API: Delete Subscription
Parameters
| Name |
Description |
subscription_id |
The identifier (id) for the subscription that you want to remove from the site. |
Exceptions
| Error |
Description |
Subscription ID undefined |
Raises an exception if a valid subscription_id is not provided. |
Example
# Remove a subscription from the site
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='SITE')
# server = TSC.Server('https://SERVERURL')
with server.auth.sign_in(tableau_auth):
server.subscriptions.delete('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
subscriptions.get
subscriptions.get(req_options=None)
Returns information about the subscriptions on the specified site.
REST API: Query Subscriptions
Parameters
| Name |
Description |
req_options |
(Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific subscription, you could specify the subject of the subscription or the id of the subscription. |
Returns
Returns a list of SubscriptionItem objects and a PaginationItem object. Use these values to iterate through the results.
subscriptions.get_by_id
subscriptions.get_by_id(subscription_id)
Returns information about the specified subscription.
REST API: Query Subscription
Parameters
| Name |
Description |
subscription_id |
The subscription_id specifies the subscription to query. |
Exceptions
| Error |
Description |
No Subscription ID provided. |
Raises an exception if a valid subscription_id is not provided. |
Returns
The SubscriptionItem. See SubscriptionItem class
Example
sub1 = server.subscriptions.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
print(sub1.subject)
subscriptions.update
subscriptions.update(subscription_item)
Updates a specific subscription. To update a subscription, you must first query it from server using the subscriptions.get() or subscriptions.get_by_id() method.
REST API: Update Subscription
Parameters
| Name |
Description |
subscription_item |
Specifies the user to subscribe, the content to subscribe to, the schedule to associate the subscription with, and other metadata for the subscription. |
Returns
Returns the updated SubscriptionItem object.
Example
# Fetch an existing subscription from server. You can also use the subscriptions.get() method
sub = server.subscriptions.get_by_id('59cec1ec-15a0-4eb3-bc9d-056b87aa0a18')
# Set update-able fields. Any of these can be added or removed.
sub.subject = "Updated subject"
sub.attach_image = True
sub.attach_pdf = True
sub.page_orientation = TSC.PDFRequestOptions.Orientation.Landscape
sub.page_size_option = TSC.PDFRequestOptions.PageType.Folio
sub.suspended = True
sub.schedule_id = 'cf2f4465-9c4b-4536-b7cc-59994e9b7dde'
sub.send_if_view_empty = True
# Create the new subscription on the site you are logged in.
sub = server.subscriptions.update(sub)
print(new_sub.subject)
Tasks
Using t
[Page truncated to keep GeezerVison snappy.]