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 asworkbooks,users,views, anddata sources. The model classes (for example, theWorkbookItem 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 theTableau Server REST API Reference. |
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 theTableauAuth class and they correspond to the attributes you specify when you sign in using the Tableau Server REST API.
TableauAuth(username,password,site_id='',user_id_to_impersonate=None)TheTableauAuth 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 theAuth.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 thecontentUrl attribute in the Tableau REST API. Thesite_id is the portion of the URL that follows the/site/ in the URL. For example, “MarketingTeam” is thesite_id in the following URLMyServer/#/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 thesite_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
importtableauserverclientasTSCtableau_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(token_name,personal_access_token,site_id='')ThePersonalAccessTokenAuth class serves the same purpose and is used in the same way asTableauAuth, but usingPersonal 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 thecontentUrl attribute in the Tableau REST API. Thesite_id is the portion of the URL that follows the/site/ in the URL. For example, “MarketingTeam” is thesite_id in the following URLMyServer/#/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 thesite_id. |
Source file: models/personal_access_token_auth.py
Example
importtableauserverclientasTSCtableau_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)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 AlsoSign in and OutServer
auth.sign_in(auth_req)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, seeServer. The authentication token keeps you signed in for 240 minutes, or until you call theauth.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 theTableauAuth. To call this method, create a server object for your server. For more information, seeSign in and Out.
REST API:Sign In
Parameters
auth_req : TheTableauAuth object that holds the sign-in credentials for the site.
Example
importtableauserverclientasTSC# create an auth objecttableau_auth=TSC.TableauAuth('USERNAME','PASSWORD')# create an instance for your serverserver=TSC.Server('https://SERVER_URL')# call the sign-in method with the auth objectserver.auth.sign_in(tableau_auth)auth.sign_out()Signs you out of the current session.
Thesign_out() method takes care of invalidating the authentication token. For more information, seeSign in and Out.
REST API:Sign Out
Example
server.auth.sign_out()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 aSiteItem retrieved fromsites.get(),sites.get_by_id() orsites.get_by_name{}. |
Example
# find and then switch auth to another site on the same serversite=server.sites.get_by_id('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')server.auth.switch_site(site)See Also
Sign in and Out
Server
The connections for Tableau Server data sources and workbooks are represented by aConnectionItem class. You can call data source and workbook methods to query or update the connection information. TheConnectionCredentials class represents the connection information you can update.
ConnectionItem()TheConnectionItem 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. |
Source file: models/connection_item.py
ConnectionCredentials(name,password,embed=True,oauth=False)TheConnectionCredentials 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, seeOAuth Connections. |
Source file: models/connection_credentials.py
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 theDatasourceItem 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 theDatasourceItem class.
DatasourceItem(project_id,name=None)TheDatasourceItem 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 newDatasourceItem instance, you must specify theproject_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 beTSC.DatasourceItem.AskDataEnablement.Enabled,TSC.DatasourceItem.AskDataEnablement.Disabled, orTSC.DatasourceItem.AskDataEnablement.SiteDefault. If no setting is specified, it will default to SiteDefault. SeeREST 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 thepopulate_connections method to access this data. See theConnectionItem 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 orexcel-direct. |
description | The description for the data source. |
encrypt_extracts | A Boolean value to determine if a datasource should be encrypted or not. SeeExtract 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 theget_by_id anddelete 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 aDatasourceItem. |
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. SeeConfigure and Manage the Bridge Client Pool for more information. |
webpage_url | The url of the datasource as displayed in browsers. |
Example
importtableauserverclientasTSC# 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
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(datasource_id)Removes the specified data source from Tableau Server.
Parameters
| Name | Description |
|---|---|
datasource_id | The identifier (id) for theDatasourceItem that you want to delete from the server. |
Exceptions
| Error | Description |
|---|---|
Datasource ID undefined | Raises an exception if a validdatasource_id is not provided. |
REST API:Delete Datasource
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 theDatasourceItem 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 isFilepath=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 parameterinclude_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) Useinclude_extract instead. The default value is to ignore this parameter (no_extract=None). If you set the parameter tono_extract=True, the download will not include an extract (if there is one). If set tono_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 validdatasource_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(req_options=None)Returns all the data sources for the site.
To get the connection information for each data source, you must first populate theDatasourceItem with connection information using thepopulate_connections(datasource_item) method. For more information, seePopulate 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 ofDatasourceItem objects and aPaginationItem object. Use these values to iterate through the results.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('USERNAME','PASSWORD')server=TSC.Server('https://SERVERURL')withserver.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.namefordatasourceinall_datasources])datasources.get_by_id(datasource_id)Returns the specified data source item.
REST API:Query Datasource
Parameters
| Name | Description |
|---|---|
datasource_id | Thedatasource_id specifies the data source to query. |
Exceptions
| Error | Description |
|---|---|
Datasource ID undefined | Raises an exception if a validdatasource_id is not provided. |
Returns
TheDatasourceItem. SeeDatasourceItem class
Example
datasource=server.datasources.get_by_id('59a57c0f-3905-4022-9e87-424fb05e9c0e')print(datasource.name)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 ofConnectionItem objects.
REST API:Query Datasource Connections
Parameters
| Name | Description |
|---|---|
datasource_item | Thedatasource_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 ofConnectionItem objects are added to the data source (datasource_item.connections).
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVERURL')#...# get the data sourcedatasource=server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')# get the connection informationserver.datasources.populate_connections(datasource)# print the information about the first connection itemconnection=datasource.connections[0]print(connection.connection_type)print(connection.id)print(connection.server_address)...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 | Thedatasource_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 newdatasource_item with aproject_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. SeeDatasourceItem. |
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. TheConnectionCredentials 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 toTrue, 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
TheDatasourceItem for the data source that was added or appended to.
Example
importtableauserverclientasTSCserver=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_itemnew_datasource=TSC.DatasourceItem(project_id)# publish data source (specified in file_path)new_datasource=server.datasources.publish(new_datasource,file_path,'CreateNew')...datasources.refresh(datasource_item)Refreshes the data of the specified extract.
REST API:Update Data Source Now
Parameters
| Name | Description |
|---|---|
datasource_item | Thedatasource_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 theDatasources.get() method to retrieve that identifies for the data sources on the server. |
Returns
A refreshedJobItem.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVERURL')# sign in ...# get the data source item to updatedatasource=server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')# call the refresh method with the data source itemrefreshed_datasource=server.datasources.refresh(datasource)datasource.update(datasource_item)Updates the specified data source.
REST API:Update Data Source
Parameters
| Name | Description |
|---|---|
datasource_item | Thedatasource_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 theDatasources.get() method to retrieve that identifies for the data sources on the server. |
Returns
An updatedDatasourceItem.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVERURL')# sign in ...# get the data source item to updatedatasource=server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')# do some updatingdatasource.owner_id='New Owner ID'# call the update method with the data source itemupdated_datasource=server.datasources.update(datasource)datasource.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 | Thedatasource_item specifies the data source to update. |
connection_item | Theconnection_item that has the information you want to update. |
Returns
An updatedConnectionItem for the data source.
Example
See theupdate_connection.py sample in the Samples directory.
datasource.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 aDataSourceItem or aConnectionItem. If the datasource only contains a single connection, theDataSourceItem is sufficient to identify which data should be updated. Otherwise, for datasources with multiple connections, aConnectionItem 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 theactions. |
For more information on theactions, see theREST API docs on “Action batch description”.To create apayload Hyper file, you can useHyper API orpantab.
Returns
AJobItem for the update job on the server. Upon completion of this job, the data was updated.
Example
See theupdate_datasource_data.py sample in the Samples directory.
The TSC library provides aFilter class that you can use to filter results returned from the server.
You can use theFilter andRequestOptions classes to filter and sort the following endpoints:
For more information, seeFilter and Sort.
Filter(field,operator,value)TheFilter class corresponds to thefilter expressions in the Tableau REST API.
Attributes
| Name | Description |
|---|---|
Field | Defined in theRequestOptions.Field class. |
Operator | Defined in theRequestOptions.Operator class |
Value | The value to compare with the specified field and operator. |
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 theGroupItem 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 theGroupItem class.
GroupItem(name)TheGroupItem class contains the attributes for the group resources on Tableau Server. TheGroupItem 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. Thename 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 isonLogin, a license is granted for each group member when they login to a site. When the mode isonSync, a license is granted for group members each time the domain is synced. |
Example
newgroup=TSC.GroupItem('My Group')# call groups.create() with new groupThe 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(group_item,user_id):Adds a user to the specified group.
REST APIAdd User to Group
Parameters
| Name | Description |
|---|---|
group_item | Thegroup_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 itemall_groups,pagination_item=server.groups.get()mygroup=all_groups[1]# The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba'# add Ian to the groupserver.groups.add_user(mygroup,'59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba')groups.add_users(group_item,user_id):Adds multiple users to the specified group.
REST APIAdd User to Group
Version
This endpoint is available with REST API version 3.21 and up. Method added inversion v0.33
Parameters
| Name | Description |
|---|---|
group_item | Thegroup_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 itemall_groups,pagination_item=server.groups.get()mygroup=all_groups[1]# Add Viewers to the groupadded_users=server.groups.add_users(mygroup,server.users.filter(site_role=TSC.UserItem.Roles.Viewer))create(group_item)Creates a new local group in Tableau Server.
REST API:Create Group
Parameters
| Name | Description |
|---|---|
group_item | Thegroup_item specifies the group to add. You first create a new instance of aGroupItem and pass that to this method. |
ReturnsAdds newGroupItem.
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 namenewgroup=TSC.GroupItem('My Group')newgroup.minimum_site_role=TSC.UserItem.Roles.ExplorerCanPublish# call the create methodnewgroup=server.groups.create(newgroup)# print the names of the groups on the serverall_groups,pagination_item=server.groups.get()forgroupinall_groups:print(group.name,group.id)create_AD_group(group_item,asJob=False)Creates an active directory group in Tableau Server.
REST API:Create Group
Parameters
| Name | Description |
|---|---|
group_item | Thegroup_item specifies the group to add. You first create a new instance of aGroupItem and pass that to this method. |
asJob | Boolean flag used to specify an asynchronous operation. If set toTrue, the return value will be a JobItem containing the status of the queued job. SeeJobItem class. |
ReturnsReturns the createdGroupItem or aJobItem 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 namenewgroup=TSC.GroupItem('AD_Group_Name','AD_Domain_Name')newgroup.minimum_site_role=TSC.UserItem.Roles.SiteAdministratorExplorernewgroup.license_mode=TSC.GroupItem.LicenseMode.onSync# call the create methodnewgroup=server.groups.create_AD_group(newgroup)# call the create method asynchronouslynewgroup_job=server.groups.create_AD_group(newgroup,asJob=True)groups.delete(group_id)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 validgroup_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')withserver.auth.sign_in(tableau_auth):server.groups.delete('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')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 theGroupItem with user information using thegroups.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 ofGroupItem objects and aPaginationItem 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')withserver.auth.sign_in(tableau_auth):# get the groups on the serverall_groups,pagination_item=server.groups.get()# print the names of the first 100 groupsforgroupinall_groups:print(group.name,group.id)groups.populate_users(group_item,req_options=None)Populates thegroup_item with the list of users.
REST API:Get Users in Group
Parameters
| Name | Description |
|---|---|
group_item | Thegroup_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 thegroup_item is unspecified.
Returns
None. A list ofUserItem objects are added to the group (group_item.users).
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVERURL')#...# get the groupall_groups,pagination_item=server.groups.get()mygroup=all_groups[1]# get the user informationpagination_item=server.groups.populate_users(mygroup)# print the names of the usersforuserinmygroup.users:print(user.name)groups.remove_user(group_item,user_id)Removes a user from a group.
REST API:Remove User from Group
Parameters
| Name | Description |
|---|---|
group_item | Thegroup_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 thegroup_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')withserver.auth.sign_in(tableau_auth):# get a groupall_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(group_item,user_id):Removes multiple users from the specified group.
REST APIRemove User from Group
Version
This endpoint is available with REST API version 3.21 and up. Method added inversion v0.33
Parameters
| Name | Description |
|---|---|
group_item | Thegroup_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 itemall_groups,pagination_item=server.groups.get()mygroup=all_groups[1]# Remove Viewers from the groupserver.groups.remove_users(mygroup,server.users.filter(site_role=TSC.UserItem.Roles.Viewer))groups.update(group_item,as_job=False)Updates a group in Tableau Server.
REST API:Update Group
Parameters
| Name | Description |
|---|---|
group_item | Thegroup_item specifies the group to update. |
as_job | (Optional) If this value is set toTrue, the update operation will be asynchronous and return a JobItem. This is only supported for Active Directory groups. By default, this value is set toFalse. |
Exceptions
| Error | Description |
|---|---|
Group item missing ID. | Raises an error if thegroup_item is missing theid attribute. |
Local groups cannot be updated asynchronously. | Theas_job attribute was set toTrue for a local group. |
Returns
The updatedGroupItem object. Ifas_job was set toTrue, aJobItem 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 groupgroup.name="new group name"group.minimum_site_role=TSC.UserItem.Roles.SiteAdministratorExplorer## Active Directory groupgroup.minimum_site_role=TSC.UserItem.Roles.SiteAdministratorExplorergroup.license_mode=TSC.GroupItem.LicenseMode.onLogin# Update group - synchronousgroup=server.groups.update(group)# Update group - asynchronous (only for Active Directory groups)job=server.groups.update(group,as_job=True)Using the TSC library, you can get information about an asynchronous process (orjob) 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 anasJob parameter (asJob-true) that creates a background process (thejob) 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 theJobItem 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 theJobItem class.
JobItem(id,type,created_at,started_at=None,completed_at=None,finish_code=0)TheJobItem class contains information about the specified job running on Tableau Server. TheJobItem 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 | Theid of the job. |
type | The type of task. The types correspond to the job type categories listed for theQuery 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. |
The Jobs methods are based upon the endpoints for jobs in the REST API and operate on theJobItem class.
Source files: server/endpoint/jobs_endpoint.py
jobs.get_by_id(job_id)Gets information about the specified job.
REST API:Query Job
Parameters
| Name | Description |
|---|---|
job_id | Thejob_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 thejob_id is not found. |
Returns
Returns theJobItem requested.
Example
# Query a Job# import tableauserverclient as TSC# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')# server = TSC.Server('https://SERVERURL')withserver.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(job_id)Cancels the currently running job. Can be used to cancel currently running jobs like extract refreshes.
Parameters
| Name | Description |
|---|---|
job_id | Thejob_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 thejob_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')withserver.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(job_id,*,timeout=None)Waits until a given job succesfully finishes.Repeatedly polls the server usingjobs.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 | Thejob_id specifies the id of the job that we want to wait for |
timeout | Optional timeout interval in seconds.wait_for_job will raise aTimeoutError if the job is not finished after waiting fortimeout seconds. |
Returns
Returns the finalJobItem.
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 returnedJobItem might still be interesting to access e.g. start and end time ornotes.
Example
See theupdate_datasource_data.py orrefresh.py sample in the Samples directory.
Using themetadata endpoint, one can use GraphQL to query metadata on, e.g., workbooks, datasources, the fields contained within them, and the relationships between them.
The Metadata methods call theMetadata 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(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 oflists anddicts as returned by thejson package.
Example
See themetadata_query.py sample in the Samples directory.
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 fieldpageInfo with the subfieldshasNextPage andendCursor, as well as the nodes to be returned. The query must accept the variablesfirst (the number of items to return) andafterToken (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 oflists anddicts as returned by thejson package.
Example
See themetadata_paginated_query.py sample in the Samples directory.
Using the TSC library, you can get information about all metrics on a site, update, or delete metrics.
MetricItem(name:Optional[str]=None)The metrics resources for Tableau are defined in theMetricItem class. The class corresponds to the metric resource you can access using the Tableau Server REST API.
AttributesName | Description:— | :—name | Name of the metricid | The REST API id for the metricdescription | The description of the metricwebpage_url | The URL for the metriccreated_at | The datetime object for when the metric was createdupdated_at | The datetime object for when the metric was updatedsuspended | Boolean for if the metric is in a suspended stateproject_id | REST API id for the project containing the metricproject_name | The name of the project containing the metricowner_id | REST API id for the user who owns the metricview_id | REST API id for the view from which the metric was created
Source file: models/metric_item.py
The metric methods are based upon the endpoints for metrics in the REST API and operate on theMetricItem class. The metrics endpoint also supports the django style filtering.SeeFilter and Sort for more information.
Source files: server/endpoint/metrics_endpoint.py
metrics.delete(metric_id)Deletes a metric item from a site.
To specify the site, create aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth 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, etcserver.metrics.delete("6561daa3-20e8-407f-ba09-709b178c0b4a")metrics.get()Return a list of metrics items for a site.
To specify the site, create aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth class.
REST API:List Metrics for Site
Parameters
None.
Returns
Returns a Tuple containing a list of allMetricItem objects and aPaginationItem. Use these values to iterate through the results.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('USERNAME','PASSWORD',site_id='CONTENTURL')server=TSC.Server('https://SERVER')withserver.auth.sign_in(tableau_auth):# get all metrics on siteall_metric_items,pagination_item=server.metrics.get()print([metric.nameformetricinall_metric_items])metrics.get_by_id(metric_id)Return a specific metric item from the site.
To specify the site, create aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth class.
REST API:Get Metric
Parameters
| Name | Description |
|---|---|
metric_id | The id of the desired metric |
Returns
Returns aMetricItem object corresponding to the ID requested.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://MY-SERVER')# sign in, etcserver.metrics.get_by_id("6561daa3-20e8-407f-ba09-709b178c0b4a")metrics.update(item)Updates a metric item on the Tableau Server.
To specify the site, create aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth class.
REST API:Update Metric
Parameters
| Name | Description |
|---|---|
metric_item | The alteredMetricItem to be updated on the Tableau Server |
Returns
Returns aMetricItem object reflecting the changes applied to Tableau Server.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://MY-SERVER')# sign in, etcmetric=server.metrics.get_by_id("6561daa3-20e8-407f-ba09-709b178c0b4a")metric.owner_id="1bbbc2b9-847d-443c-9a1f-dbcf112b8814"server.metrics.update(metric)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 theProjectItem 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 theProjectItem class.
ProjectItem(name,description=None,content_permissions=None,parent_id=None)The project resources for Tableau are defined in theProjectItem 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 eitherLockedToProject,ManagedByOwner orLockedToProjectWithoutNested. |
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, seeUse Projects to Manage Content Access. |
Source file: models/project_item.py
TheProjectItem class has a sub-class that defines the permissions for the project (ProjectItem.ContentPermissions). The options areLockedToProject,ManagedByOwner andLockedToProjectWithoutNested. For information on these content permissions, seeLock 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, etclocked_true=TSC.ProjectItem.ContentPermissions.LockedToProjectprint(locked_true)# prints 'LockedToProject'by_owner=TSC.ProjectItem.ContentPermissions.ManagedByOwnerprint(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')The project methods are based upon the endpoints for projects in the REST API and operate on theProjectItem class.
Source files: server/endpoint/projects_endpoint.py
projects.create(project_item)Creates a project on the specified site.
To create a project, you first create a new instance of aProjectItem and pass it to the create method. To specify the site to create the new project, create aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth class.
REST API:Create Project
Parameters
| Name | Description |
|---|---|
project_item | Specifies the properties for the project. Theproject_item is the request package. To create the request package, create a new instance ofProjectItem. |
ReturnsReturns the new project item.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('USERNAME','PASSWORD',site_id='CONTENTURL')server=TSC.Server('https://SERVER')withserver.auth.sign_in(tableau_auth):# create project itemnew_project=TSC.ProjectItem(name='Example Project',content_permissions='LockedToProject',description='Project created for testing')# create the projectnew_project=server.projects.create(new_project)projects.get()Return a list of project items for a site.
To specify the site, create aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth class.
REST API:Query Projects
Parameters
None.
Returns
Returns a list of allProjectItem objects and aPaginationItem. Use these values to iterate through the results.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('USERNAME','PASSWORD',site_id='CONTENTURL')server=TSC.Server('https://SERVER')withserver.auth.sign_in(tableau_auth):# get all projects on siteall_project_items,pagination_item=server.projects.get()print([proj.nameforprojinall_project_items])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 aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth 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.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://MY-SERVER')# sign in, etc...# get list of projectsall_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 projectupdated_project=server.projects.update(my_project)projects.delete(project_id)Deletes a project by ID.
To specify the site, create aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth 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(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(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(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(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(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(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(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(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(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(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(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(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)The TSC library provides aRequestOptions class that you can use to filter results returned from the server.
You can use theSort andRequestOptions classes to filter and sort the following endpoints:
You can use theImageRequestOptions andPDFRequestOptions to set options for views returned as images and PDF files.
For more information about filtering and sorting, seeFilter and Sort.
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 ofSort objects. |
filter() | Returns an iterable set ofFilter objects. |
TheRequestOptions.Field class corresponds to the fields used in filter expressions in the Tableau REST API. For more information, seeFiltering 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 |
Specifies the operators you can use to filter requests.
Attributes
| Operator | Description |
|---|---|
Equals | Sets the operator to equals (same aseq in the REST API).TSC.RequestOptions.Operator.Equals |
GreaterThan | Sets the operator to greater than (same asgt in the REST API).TSC.RequestOptions.Operator.GreaterThan |
GreaterThanOrEqual | Sets the operator to greater than or equal (same asgte in the REST API).TSC.RequestOptions.Operator.GreaterThanOrEqual |
LessThan | Sets the operator to less than (same aslt in the REST API).TSC.RequestOptions.Operator.LessThan |
LessThanOrEqual | Sets the operator to less than or equal (same aslte in the REST API).TSC.RequestOptions.Operator.LessThanOrEqual |
In | Sets the operator to in (same asin in the REST API).TSC.RequestOptions.Operator.In |
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(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 amaxage value. Seeviews.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 between1 and240 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 filterscsv_req_option=TSC.CSVRequestOptions(maxage=5)csv_req_option.vf('Region','South')csv_req_option.vf('Category','Furniture')# retrieve the csv data for the viewserver.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 theCSVRequestOptions object. For example, if you have a parameter namedRegion in the workbook, you can set the parameter value toSouth as follows:
# import tableauserverclient as TSC# server = TSC.Server('https://MY-SERVER')# sign in, get a specific view, etc.# set view filterscsv_req_option=TSC.CSVRequestOptions(maxage=5)csv_req_option.parameter('Region','South')# retrieve the csv data for the viewserver.views.populate_csv(view_item,csv_req_option)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 amaxage value. Seeviews.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 between1 and240 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 filtersexcel_req_option=TSC.ExcelRequestOptions(maxage=5)excel_req_option.vf('Region','South')excel_req_option.vf('Category','Furniture')# retrieve the excel data for the viewserver.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 theExcelRequestOptions object. For example, if you have a parameter namedRegion in the workbook, you can set the parameter value toSouth as follows:
# import tableauserverclient as TSC# server = TSC.Server('https://MY-SERVER')# sign in, get a specific view, etc.# set view filtersexcel_req_option=TSC.ExcelRequestOptions(maxage=5)excel_req_option.parameter('Region','South')# retrieve the excel data for the viewserver.views.populate_excel(view_item,excel_req_option)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. Seeviews.populate_image.
Attributes
| Name | Description |
|---|---|
imageresolution | The resolution of the view returned as an image. If unspecified, theviews.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 between1 and240 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 thevf('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 optionimage_req_option=TSC.ImageRequestOptions(imageresolution=TSC.ImageRequestOptions.Resolution.High,maxage=1)# (optional) set a view filterimage_req_option.vf('Category','Furniture')# retrieve the image for the viewserver.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 theImageRequestOptions object. For example, if you have a parameter namedRegion in the workbook, you can set the parameter value toSouth as follows:
# import tableauserverclient as TSC# server = TSC.Server('https://MY-SERVER')# sign in, get a specific view, etc.# set view filtersimage_req_option=TSC.ImageRequestOptions(maxage=5)image_req_option.parameter('Region','South')# retrieve the image data for the viewserver.views.populate_image(view_item,image_req_option)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 amaxage value. Seeviews.populate_pdf.
Attributes
| Name | Description |
|---|---|
page_type | The type of page returned in PDF format for the view. The page_type is set using thePageType class:PageType.A3PageType.A4PageType.A5PageType.B5PageType.ExecutivePageType.FolioPageType.LedgerPageType.LegalPageType.LetterPageType.NotePageType.QuartoPageType.TabloidPageType.Unspecified |
orientation | The orientation of the page. The options are portrait and landscape. The options are set using theOrientation class:Orientation.PortraitOrientation.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 between1 and240 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 FiltersYou can use thevf('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 optionspdf_req_option=TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4,orientation=TSC.PDFRequestOptions.Orientation.Landscape,maxage=1)# (optional) set a view filterpdf_req_option.vf('Region','West')# retrieve the PDF for a viewserver.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 optionspdf_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 thePDFRequestOptions object. For example, if you have a parameter namedRegion in the workbook, you can set the parameter value toSouth as follows:
# import tableauserverclient as TSC# server = TSC.Server('https://MY-SERVER')# sign in, get a specific view, etc.# set view filterspdf_req_option=TSC.PDFRequestOptions(maxage=5)pdf_req_option.parameter('Region','South')# retrieve the pdf data for the viewserver.views.populate_pdf(view_item,pdf_req_option)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 theScheduleItem 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 theJobItem class.
ScheduleItem(name,priority,schedule_type,execution_order,interval_item)TheScheduleItem class contains information about the specified schedule running on Tableau Server. TheScheduleItem 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 | Thename of the schedule. |
priority | The priority of the schedule (integer). Lower values represent higher priorities, with0 indicating the highest priority. |
schedule_type | The type of task. The types are either anExtract for an extract refresh task or aSubscription for a scheduled subscription. |
execution_order | Specifies how the scheduled task should run. The choices areParallelwhich uses all available background processes for this scheduled task, orSerial, which limits this schedule to one background process. |
interval_item | Specifies the frequency that the scheduled task should run. Theinterval_item is an instance of theIntervalItem class. Theinterval_item has properties for frequency (hourly, daily, weekly, monthly), and what time and date the scheduled item runs. You set this value by declaring anIntervalItem object that is one of the following:HourlyInterval,DailyInterval,WeeklyInterval, orMonthlyInterval. |
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 theHourlyInterval class and assign the following values:start_time,end_time, andinterval_value. To set thestart_time andend_time, assign the time value using this syntax:start_time=time(hour,minute) andend_time=time(hour,minute). Thehour is specified in 24 hour time. Theinterval_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 theDailyInterval and assign thestart_time. The start time uses the syntaxstart_time=time(hour,minute). |
WeeklyInterval | Runs the scheduled item once a week. To set the weekly interval, you create an instance of theWeeklyInterval and assign the start time and multiple instances for theinterval_value (days of week and start time). The start time uses the syntaxtime(hour,minute). Theinterval_value is the day of the week, expressed as aIntervalItem. For exampleTSC.IntervalItem.Day.Monday for Monday. |
MonthlyInterval | Runs the scheduled item once a month. To set the monthly interval, you create an instance of theMonthlyInterval and assign the start time and day. The |
The schedule methods are based upon the endpoints for schedules in the REST API and operate on theScheduleItem class.
Source files: server/endpoint/schedules_endpoint.py
schedules.add_to_schedule(schedule_id,workbook=None,datasource=None,flow=None,task_type=None)Adds aDatasourceItem,FlowItem, orWorkbookItem 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 aScheduleItem, e.g., by performingschedules.get(). |
workbook | (Optional) AWorkbookItem that should be added to the schedule. Only provide eitherworkbook ordatasource, passing multiple items will be deprecated. |
datasource | (Optional) ADatasourceItem that should be added to the schedule. Only provide eitherworkbook ordatasource, passing multiple items will be deprecated. |
flow | (Optional) AFlowItem that should be added to the schedule. Only applicable ifworkbook = None anddatasource = None. |
task_type | (Optional) Determines the type of task. One ofTaskItem.Type:ExtractRefresh,DataAcceleration,RunFlow. |
ReturnsReturns a List ofAddResponses.
Example
importtableauserverclientasTSC# sign in, etc.# get a datasource item that should be added to a scheduledatasource_item=server.datasources.get("d14dd951-01c1-4879-8bc2-e96d7dec9f0")# retrieve the id of the target scheduleschedule_id=schedule_item.id# can be a freshly created schedule or one queried via `schedules.get()`# Add the data source to the scheduleserver.schedules.add_to_schedule(schedule_id=schedule_id,datasource=datasource_item,)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 ofScheduleItem and pass it to thecreate method. TheScheduleItem includes theIntervalItem which specifies the frequency, or interval, that the schedule should run. |
Returns
Returns a new instance ofschedule_item.
Exceptions
| Error | Description |
|---|---|
Interval item must be defined. | Raises an exception if theschedule_item.interval_item is not specified. The interval item specifies whether the interval is hourly, daily, weekly, or monthly. |
Example
importtableauserverclientasTSCfromdatetimeimporttime# sign in, etc.# Create an interval to run every 2 hours between 2:30AM and 11:00PMhourly_interval=TSC.HourlyInterval(start_time=time(2,30),end_time=time(23,0),interval_value=2)# Create schedule itemhourly_schedule=TSC.ScheduleItem("Hourly-Schedule",50,TSC.ScheduleItem.Type.Extract,TSC.ScheduleItem.ExecutionOrder.Parallel,hourly_interval)# Create schedulehourly_schedule=server.schedules.create(hourly_schedule)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 theschedule.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(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(schedule_item)Parameters
| Name | Description |
|---|---|
schedule_item | The settings for the schedule that you want to update. You need to fetch an existing instance ofScheduleItem from theget method, make your changes, and then pass it to theupdate method to update the schedule on the server. TheScheduleItem includes theIntervalItem which specifies the frequency, or interval, that the schedule should run. |
REST API:Update Schedules
Hourly schedule example
importtableauserverclientasTSCfromdatetimeimporttime# sign in, etc.# Create an interval to run every 2 hours between 2:30AM and 11:00PMhourly_interval=TSC.HourlyInterval(start_time=time(2,30),end_time=time(23,0),interval_value=2)# Create schedule itemhourly_schedule=TSC.ScheduleItem("Hourly-Schedule",50,TSC.ScheduleItem.Type.Extract,TSC.ScheduleItem.ExecutionOrder.Parallel,hourly_interval)# Create schedulehourly_schedule=server.schedules.create(hourly_schedule)Daily schedule example
importtableauserverclientasTSCfromdatetimeimporttime# sign in, etc.# Create a daily interval to run every day at 12:30AMdaily_interval=TSC.DailyInterval(start_time=time(0,30))# Create schedule item using daily intervaldaily_schedule=TSC.ScheduleItem("Daily-Schedule",60,TSC.ScheduleItem.Type.Subscription,TSC.ScheduleItem.ExecutionOrder.Serial,daily_interval)# Create daily scheduledaily_schedule=server.schedules.create(daily_schedule)Weekly schedule example
importtableauserverclientasTSCfromdatetimeimporttime# sign in, etc.# Create a weekly interval to run every Monday, Wednesday, and Friday at 7:15PMweekly_interval=TSC.WeeklyInterval(time(19,15),TSC.IntervalItem.Day.Monday,TSC.IntervalItem.Day.Wednesday,TSC.IntervalItem.Day.Friday)# Create schedule item using weekly intervalweekly_schedule=TSC.ScheduleItem("Weekly-Schedule",70,TSC.ScheduleItem.Type.Extract,TSC.ScheduleItem.ExecutionOrder.Serial,weekly_interval)# Create weekly scheduleweekly_schedule=server.schedules.create(weekly_schedule)Monthly schedule example
importtableauserverclientasTSCfromdatetimeimporttime# sign in, etc.# Create a monthly interval to run on the 15th of every month at 11:30PMmonthly_interval=TSC.MonthlyInterval(start_time=time(23,30),interval_value=15)# Create schedule item using monthly intervalmonthly_schedule=TSC.ScheduleItem("Monthly-Schedule",80,TSC.ScheduleItem.Type.SubscriptionTSC.ScheduleItem.ExecutionOrder.Parallel,monthly_interval)# Create monthly schedulemonthly_schedule=server.schedules.create(monthly_schedule)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 aServer 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(server_address)TheServer class contains the attributes that represent the server on Tableau Server. After you create an instance of theServer 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, theversion 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 ofversion 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, seeREST API Versions. |
Example
importtableauserverclientasTSC# create a instance of serverserver=TSC.Server('https://MY-SERVER')# sign in, etc.# change the REST API version to match the serverserver.use_server_version()# or change the REST API version to match a specific version# for example, 2.8# server.version = '2.8'When you create an instance of theServer 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. SeeAuth |
| server.views | Access the server views and methods. SeeViews |
| server.users | Access the user resources and methods. SeeUsers |
| server.sites | Access the sites. SeeSites |
| server.groups | Access the groups resources and methods. SeeGroups |
| server.jobs | Access the jobs resources and methods. SeeJobs |
| server.workbooks | Access the resources and methods for workbooks. SeeWorkbooks |
| server.datasources | Access the resources and methods for data sources. SeeData Sources |
| server.projects | Access the resources and methods for projects. SeeProjects |
| server.schedules | Access the resources and methods for schedules. SeeSchedules |
| server.subscriptions | Access the resources and methods for subscriptions. SeeSubscriptions |
| server.server_info | Access the resources and methods for server information. SeeServerInfo class |
TheServer class hasPublishMode class that enumerates the options that specify what happens when you publish a workbook or data source. The options areOverwrite,Append, orCreateNew.
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
importtableauserverclientasTSC# login, etc.print(TSC.Server.PublishMode.Overwrite)# prints 'Overwrite'overwrite_true=TSC.Server.PublishMode.Overwrite...# pass the PublishMode to the publish workbooks methodnew_workbook=server.workbooks.publish(new_workbook,args.filepath,overwrite_true)ServerInfoItem(product_version,build_number,rest_api_version)TheServerInfoItem class contains the build and version information for Tableau Server. The server information is accessed with theserver_info.get() method, which returns an instance of theServerInfo 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 theServer.version attribute. To take advantage of new features, you should query the server and set theServer.version to match the supported REST API version number. |
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 |
|---|---|
404003UNKNOWN_RESOURCE | Raises an exception if the server info endpoint is not found. |
Example
importtableauserverclientasTSC# create a instance of serverserver=TSC.Server('https://MY-SERVER')# set the version number > 2.3# the server_info.get() method works in 2.4 and laterserver.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))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 theSiteItem 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 theSiteItem 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)TheSiteItem class contains the members or attributes for the site resources on Tableau Server or Tableau Cloud. TheSiteItem 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. SpecifyContentAndUsers to allow site administrators to use the server interface andtabcmd commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) SpecifyContentOnly 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, thenuser_quota will equal the sum of the tiered capacity values, and attempting to setuser_quota will cause an error. |
Tiered capacity attributes:tier_explorer_capacitytier_creator_capacitytier_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) Specifytrue to prevent users from being able to subscribe to workbooks on the specified site. The default isfalse. |
subscribe_others_enabled | (Optional) Specifyfalse 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 istrue. |
revision_history_enabled | (Optional) Specifytrue to enable revision history for content resources (workbooks and datasources). The default isfalse. |
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 orSuspended). |
Example
# create a new instance of a SiteItemnew_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
TheSiteAuthConfiguration class contains the attributes for the authentication configuration on Tableau Cloud. This class represents the authentication configuration information returned when using thesites.list_authentication_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 siteauth_configs=server.sites.list_authentication_configurations()# Display configuration detailsforconfiginauth_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}")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(site_item)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 ofSiteItem and pass it to thecreate method. |
Returns
Returns a new instance ofSiteItem.
Example
importtableauserverclientasTSC# create an instance of serverserver=TSC.Server('https://MY-SERVER')# create shortcut for admin modecontent_users=TSC.SiteItem.AdminMode.ContentAndUsers# create a new SiteItemnew_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 SiteItemnew_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 allSiteItem objects and aPaginationItem. Use these values to iterate through the results.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://MY-SERVER')# sign in, etc.# query the sitesall_sites,pagination_item=server.sites.get()# print all the site names and idsforsiteinall_sites:print(site.id,site.name,site.content_url,site.state)sites.get_by_id(site_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 theSiteItem.
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(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 theSiteItem.
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(site_item)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 theuser_quota, theAdminMode must be set toContentAndUsers |
Returns
Returns the updatedsite_item.
Example
...# make some updates to an existing site_itemsite_item.name="New name"# call updatesite_item=server.sites.update(site_item)...Sites.delete(site_id)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_authentication_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_authentication_configurations()forconfiginauth_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}")TheSort 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:
sort(field,direction)Attributes
| Name | Description |
|---|---|
field | Sets the field to sort on. The fields are defined in theRequestOption class. |
direction | The direction to sort, either ascending (Asc) or descending (Desc). The options are defined in theRequestOptions.Direction class. |
Example
# create a new instance of a request option objectreq_option=TSC.RequestOptions()# add the sort expression, sorting by name and directionreq_option.sort.add(TSC.Sort(TSC.RequestOptions.Field.Name,TSC.RequestOptions.Direction.Asc))matching_workbooks,pagination_item=server.workbooks.get(req_option)forwbinmatching_workbooks:print(wb.name)For information about using theSort class, seeFilter and Sort.
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.
The subscription resources for Tableau Server are defined in theSubscriptionItem 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 theSubscriptionItem class.
SubscriptionItem(subject,schedule_id,user_id,target)Attributes
| Name | Description |
|---|---|
id | The id of the subscription on the site. |
attach_image | Setting this toTrue will cause the subscriber to receive mail with .png images of workbooks or views attached to it. By default, this value is set toTrue. Ifattach_pdf is set toFalse, then this value cannot be set toFalse. |
attach_pdf | Setting this toTrue 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 toFalse. |
message | The text body of the subscription email message. |
page_orientation | The orientation of the pages produced whenattach_pdf isTrue. If this parameter is not present the page orientation will default toPortrait. See chart below for a full list of values. |
page_size_option | The type of page produced, which determines the page dimensions whenattach_pdf isTrue. If this parameter is not present the page type will default toLetter. 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 (seetarget attribute). IfTrue, an image is sent even if the view specified in a subscription is empty. IfFalse, nothing is sent if the view is empty. The default value isTrue. |
subject | The subject of the subscription. This is the description that you provide to identify the subscription. |
suspended | Setting this value toTrue stops email delivery for the specified subscription. Setting it toFalse 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 thetarget class. Thetarget has two properties, theid of the workbook or view (target.id), and thetype (target.type), which can eitherview orworkbook. Thesend_if_view_empty attribute can only be set toTrue if thetarget.type is set toView. |
user_id | The identifier of the user (person) who receives the subscription. |
Valid PDF options (applies only ifattach_pdf is set toTrue)
| Attribute | Valid options |
|---|---|
page_orientation | TSC.PDFRequestOptions.Orientation.LandscapeTSC.PDFRequestOptions.Orientation.Portrait |
page_size_option | TSC.PDFRequestOptions.PageType.A3TSC.PDFRequestOptions.PageType.A4TSC.PDFRequestOptions.PageType.A5TSC.PDFRequestOptions.PageType.B5TSC.PDFRequestOptions.PageType.ExecutiveTSC.PDFRequestOptions.PageType.FolioTSC.PDFRequestOptions.PageType.LedgerTSC.PDFRequestOptions.PageType.LegalTSC.PDFRequestOptions.PageType.LetterTSC.PDFRequestOptions.PageType.NoteTSC.PDFRequestOptions.PageType.QuartoTSC.PDFRequestOptions.PageType.Tabloid |
Source files:server/endpoints/subscription_item.pyserver/request_options.py
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
subscription.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 thesubscription_item.
To create a new subscription you need to first create a newsubscription_item (fromSubscriptionItem 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 newSubscriptionItem 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=Falsenew_sub.attach_pdf=Truenew_sub.message="You have an alert!"new_sub.page_orientation=TSC.PDFRequestOptions.Orientation.Landscapenew_sub.page_size_option=TSC.PDFRequestOptions.PageType.B4new_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(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 validsubscription_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')withserver.auth.sign_in(tableau_auth):server.subscriptions.delete('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')subscription.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. |
ReturnsReturns a list ofSubscriptionItem objects and aPaginationItem object. Use these values to iterate through the results.
subscription.get_by_id(subscription_id)Returns information about the specified subscription.
REST API:Query Subscription
Parameters
| Name | Description |
|---|---|
subscription_id | Thesubscription_id specifies the subscription to query. |
Exceptions
| Error | Description |
|---|---|
No Subscription ID provided. | Raises an exception if a validsubscription_id is not provided. |
Returns
TheSubscriptionItem. SeeSubscriptionItem class
Example
sub1=server.subscription.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')print(sub1.subject)subscription.update(subscription_item)Updates a specific subscription. To update a subscription, you must first query it from server using thesubscriptions.get() orsubscriptions.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 updatedSubscriptionItem object.
Example
# Fetch an existing subscription from server. You can also use the subscriptions.get() methodsub=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=Truesub.attach_pdf=Truesub.page_orientation=TSC.PDFRequestOptions.Orientation.Landscapesub.page_size_option=TSC.PDFRequestOptions.PageType.Foliosub.suspended=Truesub.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)Using the TSC library, you can get information about all the tasks on a site and you can remove tasks. To create new tasks seeSchedules.
The task resources for Tableau Server are defined in theTaskItem class. The class corresponds to the task resources you can access using the Tableau Server REST API. The task methods are based upon the endpoints for tasks in the REST API and operate on theTaskItem class.
TaskItem(id,task_type,priority,consecutive_failed_count=0,schedule_id=None,target=None)Attributes
| Name | Description |
|---|---|
id | The id of the task on the site. |
task_type | Type of extract task - full or incremental refresh. |
priority | The priority of the task on the server. |
consecutive_failed_count | The number of failed consecutive executions. |
schedule_id | The id of the schedule on the site. |
target | An object,datasource orworkbook, which is associated to the task. Source file: models/target.py |
Example
# import tableauserverclient as TSC# server = TSC.Server('server')task=server.tasks.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')print(task)Source file: models/task_item.py
The Tableau Server Client provides several methods for interacting with task resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
Source file: server/endpoint/tasks_endpoint.py
tasks.get(req_options=None)Returns information about the tasks on the specified site.
REST API:Get Extract Refresh Tasks on Site
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 ofTaskItem objects and aPaginationItem object. Use these values to iterate through the results.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('USERNAME','PASSWORD')server=TSC.Server('https://SERVERURL')withserver.auth.sign_in(tableau_auth):all_tasks,pagination_item=server.tasks.get()print("\nThere are {} tasks on site: ".format(pagination_item.total_available))print([task.idfortaskinall_tasks])tasks.get_by_id(task_id)Returns information about the specified task.
REST API:Query Extract Refresh Task On Site
Parameters
| Name | Description |
|---|---|
task_id | Thetask_id specifies the task to query. |
Exceptions
| Error | Description |
|---|---|
Task ID undefined. | Raises an exception if a validtask_id is not provided. |
Returns
TheTaskItem. SeeTaskItem class
Example
task1=server.tasks.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')print(task1.task_type)tasks.run(task_item)Runs the specified extract refresh task.
To run a extract refresh task you need to first lookup the tasktask_item (TaskItem class).
REST API:Run Extract Refresh Task
Parameters
| Name | Description |
|---|---|
task_item | You can pass the method a task object. |
Returns
Returns the REST API response.
Example
# import tableauserverclient as TSC# server = TSC.Server('server')# login, etc.task=server.tasks.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')server.tasks.run(task)tasks.delete(task_id)Deletes an extract refresh task.
REST API:Delete Extract Refresh Task
Parameters
| Name | Description |
|---|---|
task_id | Thetask_id specifies the task to delete. |
Exceptions
| Error | Description |
|---|---|
Task ID undefined. | Raises an exception if a validtask_id is not provided. |
Example
server.tasks.delete('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')Using the TSC library, you can get information about all the users on a site, and you can add or remove users, or update user information.
The user resources for Tableau Server are defined in theUserItem class. The class corresponds to the user resources you can access using the Tableau Server REST API. The user methods are based upon the endpoints for users in the REST API and operate on theUserItem class.
UserItem(name,site_role,auth_setting=None)TheUserItem class contains the members or attributes for the view resources on Tableau Server. TheUserItem 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.
Attributes
| Name | Description |
|---|---|
auth_setting | This is a required attribute and is only for Tableau Cloud. The new authentication type for the user - seeUser Auth below for values. |
domain_name | The name of the site. |
external_auth_user_id | Represents ID stored in Tableau’s single sign-on (SSO) system. TheexternalAuthUserId value is returned for Tableau Cloud. For other server configurations, this field contains null. |
id | The id of the user on the site. |
last_login | The date and time the user last logged in. |
workbooks | The workbooks the user owns or has Read (view) permissions. You must run the populate_workbooks method to add the workbooks to theUserItem. |
email | The email address of the user. |
fullname | The full name of the user. |
name | The name of the user. This attribute is required when you are creating aUserItem instance. |
site_role | The role the user has on the site. This attribute is required if you are creating aUserItem instance. SeeUser Roles below for details. |
groups | The groups that the user belongs to. You must run the populate_groups method to add the groups to theUserItem. |
idp_configuration_id | Tableau Cloud only. The authentication method for the user. To find the idp_configuration_id value, use sites.list_authentication_configurations method.Important: Use idp_configuration_id or auth_setting, but not both. |
User Auth
You can assign the following values for this attribute:
OpenIDSAML (the user signs in usingSingle sign-on)TableauIDWithMFA These options appear in theAuthentication tab on theSettings page in Tableau Cloud.User Roles
The possible user roles for thesite_role attribute are the following:
CreatorExplorerExplorerCanPublishServerAdministratorSiteAdministratorExplorerSiteAdministratorCreatorUnlicensedReadOnlyViewerNote: If any operations related to a user’ssite_role cause a 400 error response (for example:Invalid site role: 'Explorer' is malformed or is not a supported user role in this version of Tableau), ensure you areusing the latest REST API version for your server.
Example
# import tableauserverclient as TSC# server = TSC.Server('server')# create a new UserItem object.newU=TSC.UserItem('Monty','Publisher')print(newU.name,newU.site_role)Source file: models/user_item.py
The Tableau Server Client provides several methods for interacting with user resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
Source file: server/endpoint/users_endpoint.py
users.add(user_item)Adds the user to the site.
To add a new user to the site you need to first create a newuser_item (fromUserItem class). When you create a new user, you specify the name of the user and their site role. For Tableau Cloud, you also specify theauth_setting attribute in your request. When you add user to Tableau Cloud, the name of the user must be the email address that is used to sign in to Tableau Cloud. After you add a user, Tableau Cloud sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password.
REST API:Add User to Site
Parameters
| Name | Description |
|---|---|
user_item | 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 user, you could specify the name of the user or the user’s id. |
Returns
Returns the newUserItem object.
Example
# import tableauserverclient as TSC# server = TSC.Server('server')# login, etc.# create a new UserItem object.newU=TSC.UserItem('Heather','Publisher')# add the new user to the sitenewU=server.users.add(newU)print(newU.name,newU.site_role)users.get(req_options=None)Returns information about the users on the specified site.
To get information about the workbooks a user owns or has view permission for, you must first populate theUserItem with workbook information using thepopulate_workbooks(user_item) 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 user, you could specify the name of the user or the user’s id. |
Returns
Returns a list ofUserItem objects and aPaginationItem object. Use these values to iterate through the results.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('USERNAME','PASSWORD')server=TSC.Server('https://SERVERURL')withserver.auth.sign_in(tableau_auth):all_users,pagination_item=server.users.get()print("\nThere are {} user on site: ".format(pagination_item.total_available))print([user.nameforuserinall_users])users.get_by_id(user_id)Returns information about the specified user.
REST API:Query User On Site
Parameters
| Name | Description |
|---|---|
user_id | Theuser_id specifies the user to query. |
Exceptions
| Error | Description |
|---|---|
User ID undefined. | Raises an exception if a validuser_id is not provided. |
Returns
TheUserItem. SeeUserItem class
Example
user1=server.users.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')print(user1.name)users.populate_favorites(user_item)Returns the list of favorites (views, workbooks, and data sources) for a user.
Not currently implemented
users.populate_groups(user_item,req_options=None):Returns the groups that the user belongs to.
REST API:Get Groups for a User
Parameters
| Name | Description |
|---|---|
user_item | Theuser_item specifies the user to populate with group membership. |
Exceptions
| Error | Description |
|---|---|
User item missing ID. | Raises an error if theuser_item is unspecified. |
Returns
A list ofGroupItem
APaginationItem that points (user_item.groups). SeeUserItem class
Example
# first get all users, call server.users.get()# get groups for user[0]...page_n=server.users.populate_groups(all_users[0])print("\nUser {0} is a member of {1} groups".format(all_users[0].name,page_n.total_available))print("\nThe groups are:")forgroupinall_users[0].groups:print(group.name)...users.populate_workbooks(user_item,req_options=None):Returns information about the workbooks that the specified user owns and has Read (view) permissions for.
This method retrieves the workbook information for the specified user. The REST API is designed to return only the information you ask for explicitly. When you query for all the users, the workbook information for each user is not included. Use this method to retrieve information about the workbooks that the user owns or has Read (view) permissions. The method adds the list of workbooks to the user item object (user_item.workbooks).
REST API:Query Workbooks for User
Parameters
| Name | Description |
|---|---|
user_item | Theuser_item specifies the user to populate with workbook information. |
Exceptions
| Error | Description |
|---|---|
User item missing ID. | Raises an error if theuser_item is unspecified. |
Returns
A list ofWorkbookItem
APaginationItem that points (user_item.workbooks). SeeUserItem class
Example
# first get all users, call server.users.get()# get workbooks for user[0]...page_n=server.users.populate_workbooks(all_users[0])print("\nUser {0} owns or has READ permissions for {1} workbooks".format(all_users[0].name,page_n.total_available))print("\nThe workbooks are:")forworkbookinall_users[0].workbooks:print(workbook.name)...users.remove(user_id)Removes the specified user from the site.
REST API:Remove User from Site
Parameters
| Name | Description |
|---|---|
user_id | The identifier (id) for the user that you want to remove from the server. |
Exceptions
| Error | Description |
|---|---|
User ID undefined | Raises an exception if a validuser_id is not provided. |
Example
# Remove a user from the site# import tableauserverclient as TSC# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')# server = TSC.Server('https://SERVERURL')withserver.auth.sign_in(tableau_auth):server.users.remove('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')users.update(user_item,password=None)Updates information about the specified user.
The information you can modify depends upon whether you are using Tableau Server or Tableau Cloud, and whether you have configured Tableau Server to use local authentication or Active Directory. For more information, seeUpdate User.
REST API:Update User
Parameters
| Name | Description |
|---|---|
user_item | Theuser_item specifies the user to update. |
password | (Optional) The new password for the user. |
Exceptions
| Error | Description |
|---|---|
User item missing ID. | Raises an error if theuser_item is unspecified. |
Returns
An updatedUserItem. SeeUserItem class
Example
# import tableauserverclient as TSC# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')# server = TSC.Server('https://SERVERURL')withserver.auth.sign_in(tableau_auth):# create a new user_itemuser1=TSC.UserItem('temp','Viewer')# add new useruser1=server.users.add(user1)print(user1.name,user1.site_role,user1.id)# modify user infouser1.name='Laura'user1.fullname='Laura Rodriguez'user1.email='laura@example.com'# update useruser1=server.users.update(user1)print("\Updated user info:")print(user1.name,user1.fullname,user1.email,user1.id)Using the TSC library, you can get information about views in a site or a workbook.
The view resources for Tableau Server are defined in theViewItem class. The class corresponds to the view resources you can access using the Tableau Server REST API. The view methods are based upon the endpoints for views in the REST API and operate on theViewItem class.
ViewItem()TheViewItem class contains the members or attributes for the view resources on Tableau Server. TheViewItem 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/view_item.py
Attributes
| Name | Description |
|---|---|
content_url | The name of the view as it would appear in a URL. |
csv | The CSV data of the view. You must first call theviews.populate_csv method to access the CSV data. |
id | The identifier of the view item. |
image | The image of the view. You must first call theviews.populate_imagemethod to access the image. |
name | The name of the view. |
owner_id | The ID for the owner of the view. |
pdf | The PDF of the view. You must first call theviews.populate_pdf method to access the PDF content. |
preview_image | The thumbnail image for the view. You must first call theviews.populate_preview_image method to access the preview image. |
project_id | The ID of the project that contains the view. |
total_views | The usage statistics for the view. Indicates the total number of times the view has been looked at. |
workbook_id | The ID of the workbook associated with the view. |
The Tableau Server Client provides methods for interacting with view resources, or endpoints. These methods correspond to the endpoints for views in the Tableau Server REST API.
Source file: server/endpoint/views_endpoint.py
views.get(req_options=None, usage=False)Returns the list of views items for a site.
REST API:Query Views for Site
Version
This endpoint is available with REST API version 2.0 and up.
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 view, you could specify the name of the view or its ID. |
usage | (Optional) If true (usage=True) returns the usage statistics for the views. The default isusage=False. |
Returns
Returns a list of allViewItem objects and aPaginationItem. Use these values to iterate through the results.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('username','password')server=TSC.Server('https://servername')withserver.auth.sign_in(tableau_auth):all_views,pagination_item=server.views.get()print([view.nameforviewinall_views])Example using Pager
You can also use the provided Pager generator to get all views on site, without having to page through the results.
forviewinTSC.Pager(server.views):print(view.name)views.get_by_id(view_id)Returns the details of a specific view.
REST API:Get View
Version
This endpoint is available REST API version 3.1 and up.
Parameters
| Name | Description |
|---|---|
view_id | The ID of the view to retrieve. |
Returns
Returns a singleViewItem object.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('username','password')server=TSC.Server('https://servername')withserver.auth.sign_in(tableau_auth):view=server.views.get_by_id('d79634e1-6063-4ec9-95ff-50acbf609ff5')print(view.name)views.populate_preview_image(view_item)Populates a preview image for the specified view.
This method gets the preview image (thumbnail) for the specified view item. The method uses theid andworkbook_id fields to query the preview image. The method populates thepreview_image for the view.
REST API:Query View Preview Image
Version
This endpoint is available with REST API version 2.0 and up.
Parameters
| Name | Description |
|---|---|
view_item | Specifies the view to populate. |
Exceptions
| Error | Description |
|---|---|
View item missing ID or workbook ID | Raises an error if the ID of the view or workbook is missing. |
Returns
None. The preview image is added toview_item and can be accessed by itspreview_image field.
Example
# Sign in, get view, etc.# Populate and save the preview image as 'view_preview_image.png'server.views.populate_preview_image(view_item)withopen('./view_preview_image.png','wb')asf:f.write(view_item.preview_image)views.populate_image(view_item,req_options=None)Populates the image of the specified view.
This method uses theid field to query the image, and populates the image content as theimage field.
REST API:Query View Image
Version
This endpoint is available with REST API version 2.5 and up.
Parameters
| Name | description |
|---|---|
view_item | Specifies the 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). SeeImageRequestOptions class for more details. |
Exceptions
| Error | Description |
|---|---|
View item missing ID | Raises an error if the ID of the view is missing. |
Returns
None. The image is added to theview_item and can be accessed by itsimage field.
Example
# Sign in, get view, etc.# Populate and save the view image as 'view_image.png'server.views.populate_image(view_item)withopen('./view_image.png','wb')asf:f.write(view_item.image)views.populate_csv(view_item, req_options=None)Populates the CSV data of the specified view.
This method uses theid field to query the CSV data, and populates the data as thecsv field.
REST API:Query View Data
Version
This endpoint is available with REST API version 2.7 and up.
Parameters
| Name | description |
|---|---|
view_item | Specifies the view to populate. |
req_options | (Optional) You can pass in request options to specify the maximum age of the CSV cached on the server. SeeCSVRequestOptions class for more details. |
Exceptions
| Error | Description |
|---|---|
View item missing ID | Raises an error if the ID of the view is missing. |
Returns
None. The CSV data is added to theview_item and can be accessed by itscsv field.
Example
# Sign in, get view, etc.# Populate and save the CSV data in a fileserver.views.populate_csv(view_item)withopen('./view_data.csv','wb')asf:# Perform byte join on the CSV dataf.write(b''.join(view_item.csv))views.populate_pdf(view_item, req_options=None)Populates the PDF content of the specified view.
This method populates a PDF with image(s) of the view you specify.
REST API:Query View PDF
Version
This endpoint is available with REST API version 2.7 and up.
Parameters
| Name | description |
|---|---|
view_item | Specifies the 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. SeePDFRequestOptions class for more details. |
Exceptions
| Error | Description |
|---|---|
View item missing ID | Raises an error if the ID of the view is missing. |
Returns
None. The PDF content is added to theview_item and can be accessed by itspdf field.
Example
# Sign in, get view, etc.# Populate and save the view pdf as 'view_pdf.pdf'server.views.populate_pdf(view_item)withopen('./view_pdf.pdf','wb')asf:f.write(view_item.pdf)
Using the Tableau Server Client (TSC), you can create a new webhook, get a list of all the webhooks, get details about a specific webhook, or delete a webhook.
The webhook resource for Tableau Server and Tableau Cloud are defined in theWebhookItem class. The class corresponds to the webhook resources you can access using the Tableau REST API. For example, using REST API, you can gather information about a workbook, like the name of the Webbook, the event it is associated with, and the destination URL, and you can get the same information using TSC as well.
Tableau webhook REST API endpoints are available inREST API version 3.16 and later.
TheWebhookItem represents the webhook resources on Tableau Server or Tableau Cloud. This is the information that can be sent or returned in response to a REST API request for webhooks.
Attributes
| Name | Description |
|---|---|
id | The identifier (luid) for the webhook. You need this value to query a specific webhook with theget_by_id method or to delete a webhook with thedelete method. |
name | The name of the webhook. You must specify this when you create an instance of theWebhookItem. |
url | The destination URL for the webhook. The webhook destination URL must be https and have a valid certificate. You must specify this when you create an instance of theWebhookItem. |
event | The name of the Tableau event that triggers your webhook.This is eitherapi-event-name orwebhook-source-api-event-name: one of these is required to create an instance of theWebhookItem. We recommend using theapi-event-name.The event name must be one of the supported events listed in theTrigger Events table. |
owner_id | The identifier of the owner of the webhook. |
Example
importtableauserverclientasTSC# Create new Webhook_itemnew_webhook=TSC.WebhookItem()Source file: models/webhook_item.py
The Tableau Server Client provides several methods for interacting with webhook resources, or endpoints. These methods correspond to endpoints in the Tableau REST API.
Source file: server/endpoint/webhooks_endpoint.py
webhooks.create(webhook_item)Creates a new webhook on a specified site.
To create a webhook, you must first create a new instance of aWebhookItem and pass it to the create method.
To specify the site to create the new webhook in, create aTableauAuth instance using the content URL for the site(site_id) and sign in to that site. For more information on how to specify a site, see theTableauAuth class.
REST API:Create Webhook
| Name | Description |
|---|---|
| webhook_item | Specifies the properties for the webhook. The webhook_item is the request package. To create a request package, create a new instance ofWebhokItem. TheWebhookItem includes thename, destinationurl, and theevent orsource. Theevent orsource specifies the Tableau event that should be associated with the webhook. |
Returns Returns the new webhook item.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVER')# sign in . For authentication examples, see https://github.com/tableau/server-client-python/blob/master/samples/login.py# create a webhook itemwithserver.auth.sign_in(tableau_auth):new_webhook=TSC.WebhookItem()new_webhook.name='testWebhook'new_webhook.event="workbook-refresh-failed"# alternately, you can also use new_webhook.source="webhook-source-event-workbook-refresh-failed"new_webhook.url="https://webhook.site/6e4c957d-dd40-422c-8fc6-7151afe7fc0b"# create the webhooknew_webhook=server.webhooks.create(new_webhook)print("Webhook created. ID: {}".format(new_webhook.id))webhooks.delete(webhook_id)Deletes a webhook by ID.
To specify the site, create aTableauAuth instance using the content URL for the site(site_id) and sign in to the site. For more information on how to specify a site, see theTableauAuth class.
REST API:Delete Webhook
Parameters
| Name | Description |
|---|---|
webhook_id | The ID of the webhook to delete. |
Exceptions
| Error | Description |
|---|---|
Webhook ID undefined | Raises an exception if awebhook_id is not provided. |
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVER')# sign in . For authentication examples, see https://github.com/tableau/server-client-python/blob/master/samples/login.py# Delete the webhookwithserver.auth.sign_in(tableau_auth):server.webhooks.delete('7d60d364-b9f5-4a9c-8aa5-4bdaa38c5dd3')webhooks.get()Returns a list of all the webhooks for a site.
To specify the site, create aTableauAuth instance using the content URL for the site(site_id), and sign in to that site. For more information on how to specify a site, see theTableauAuth class.
REST API:List Webhooks
Parameters
| Name | Description |
|---|---|
req_option | (Optional) You can pass themthod oa request object that contains additional parameters to filter the request. For example, you could specify the name of the webhook or the name of the owner. For more information, seeFilter and Sort. |
Returns
Returns a list of allProjectItem objects and aPagainationItem. Use these values to iterate through the results.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVER')# sign in . For authentication examples, see https://github.com/tableau/server-client-python/blob/master/samples/login.py# get a list of all the webhooks on a sitewithserver.auth.sign_in(tableau_auth):all_webhooks,pagination_item=server.webhooks.get()print("\nThere are {} webhooks on site: ".format(pagination_item.total_available))print(["Webhook Name:"+webhook.name+";"+"ID:"+webhook.idforwebhookinall_webhooks])webhooks.get_by_ide(webhook_id)Returns information about the specified workbook for a site.
To specify the site, create aTableauAuth instance using the content URL for the site(site_id), and sign in to that site. For more information on how to specify a site, see theTableauAuth class.
Parameters
| Name | Description |
|---|---|
webhook_id | The ID of the webhook. The ID is aluid. |
Exceptions
| Error | Description |
|---|---|
Webhook ID undefined | Raises an exception if awebhook_id is not provided. |
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVER')# sign in . For authentication examples, see https://github.com/tableau/server-client-python/blob/master/samples/login.pywithserver.auth.sign_in(tableau_auth):webhook=server.webhooks.get_by_id('7d60d364-b9f5-4a9c-8aa5-4bdaa38c5dd3')print(webhook.name,webhook.url)Using the TSC library, you can get information about a specific workbook or all the workbooks on a site, and you can publish, update, or delete workbooks.
The project resources for Tableau are defined in theWorkbookItem class. The class corresponds to the workbook resources you can access using the Tableau REST API. The workbook methods are based upon the endpoints for projects in the REST API and operate on theWorkbookItem class.
WorkbookItem(project_id,name=None,show_tabs=False)The workbook resources for Tableau are defined in theWorkbookItem class. The class corresponds to the workbook resources you can access using the Tableau REST API. Some workbook methods take an instance of theWorkbookItem class as arguments. The workbook item specifies the project
Attributes
| Name | Description |
|---|---|
connections | The list of data connections (ConnectionItem) for the data sources used by the workbook. You must first call theworkbooks.populate_connections method to access this data. See theConnectionItem 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. |
description | The user-defined description of the workbook |
id | The identifier for the workbook. You need this value to query a specific workbook or to delete a workbook with theget_by_id anddelete methods. |
name | The name of the workbook. |
owner_id | The ID of the owner. |
preview_image | The thumbnail image for the view. You must first call theworkbooks.populate_preview_image method to access this data. |
project_id | The project id. |
project_name | The name of the project. |
size | The size of the workbook (in megabytes). |
show_tabs | (Boolean) Determines whether the workbook shows tabs for the view. |
hidden_views | (Optional) List of string names of views that need to be hidden when the workbook is published. |
tags | The tags that have been added to the workbook. |
updated_at | The date and time when the workbook was last updated. |
views | The list of views (ViewItem) for the workbook. You must first call theworkbooks.populate_views method to access this data. See theViewItem class. |
webpage_url | The full URL of the workbook. |
Example
# creating a new instance of a WorkbookItem#importtableauserverclientasTSC# Create new workbook_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39'new_workbook=TSC.WorkbookItem('3a8b6148-493c-11e6-a621-6f3499394a39')Source file: models/workbook_item.py
The Tableau Server Client (TSC) library provides methods for interacting with workbooks. These methods correspond to endpoints in the Tableau Server REST API. For example, you can use the library to publish, update, download, or delete workbooks on the site.The methods operate on a workbook object (WorkbookItem) that represents the workbook resources.
Source files: server/endpoint/workbooks_endpoint.py
workbooks.get(req_options=None)Queries the server and returns information about the workbooks the site.
REST API:Query Workbooks 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 workbook, you could specify the name of the workbook or the name of the owner. SeeFilter and Sort |
Returns
Returns a list of allWorkbookItem objects and aPaginationItem. Use these values to iterate through the results.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('username','password',site_id='site')server=TSC.Server('https://servername')withserver.auth.sign_in(tableau_auth):all_workbooks_items,pagination_item=server.workbooks.get()# print names of first 100 workbooksprint([workbook.nameforworkbookinall_workbooks_items])workbooks.get_by_id(workbook_id)Returns information about the specified workbook on the site.
REST API:Query Workbook
Parameters
| Name | Description |
|---|---|
workbook_id | Theworkbook_id specifies the workbook to query. The ID is a LUID (64-bit hexadecimal string). |
Exceptions
| Error | Description |
|---|---|
Workbook ID undefined | Raises an exception if aworkbook_id is not provided. |
Returns
TheWorkbookItem. SeeWorkbookItem class
Example
workbook=server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')print(workbook.name)workbooks.publish(workbook_item,file_path,publish_mode,connections,skip_connection_check,as_job)Publish a workbook to the specified site.
Note: The REST API cannot automatically includeextracts or other resources that the workbook uses. Therefore, a .twb file that uses data from an Excel or csv file on a local computer cannot be published,unless you package the data and workbook in a .twbx file, or publish the data source separately.
For workbooks that are larger than 64 MB, the publish method automatically takes care of chunking the file in parts for uploading. Using this method is considerably more convenient than calling the publish REST APIs directly.
REST API:Publish Workbook,Initiate File Upload,Append to File Upload
Parameters
| Name | Description |
|---|---|
workbook_item | Theworkbook_item specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of aworkbook_item that includes aproject_id of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. SeeWorkbookItem. |
file | The file path or file object of the workbook to publish. When providing a file object, you must also specifiy the name of the workbook in your instance of theworkbook_itemworkbook_item , as the name cannot be derived from the file name. |
mode | Specifies whether you are publishing a new workbook (CreateNew) or overwriting an existing workbook (Overwrite). You cannot appending workbooks. You can also use the publish mode attributes, for example:TSC.Server.PublishMode.Overwrite. |
connections | List ofConnectionItems objects for the connections created within the workbook. |
skip_connection_check | (Optional) Set toTrue to skip connection check at time of upload. Publishing will succeed but unchecked connection issues may result in a non-functioning workbook. Defaults toFalse. |
as_job | (Optional) Set toTrue to run the upload as a job (asynchronous upload). If set toTrue a job will start to perform the publishing process and aJob object is returned. Defaults toFalse. |
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. |
Workbooks cannot be appended. | Themode must be set toOverwrite orCreateNew. |
Only .twb or twbx files can be published as workbooks. | Raises an error if the type of file specified is not supported. |
See the REST APIPublish Workbook for additional error codes.
Returns
TheWorkbookItem for the workbook that was published.
Example
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('username','password',site_id='site')server=TSC.Server('https://servername')withserver.auth.sign_in(tableau_auth):# create a workbook itemwb_item=TSC.WorkbookItem(name='Sample',project_id='1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e')# set hidden viewswb_item.hidden_views=['Sheet1','Sheet2']# call the publish method with the workbook itemwb_item=server.workbooks.publish(wb_item,'SampleWB.twbx','Overwrite')workbooks.refresh(workbook_item)Refreshes the extract of an existing workbook.
REST API:Update Workbook Now
Parameters
| Name | Description |
|---|---|
workbook_item | Theworkbook_item specifies the settings for the workbook you are refreshing. |
Exceptions
| Error | Description |
|---|---|
Workbook item missing ID. Workbook must be retrieved from server first. | Raises an error if theworkbook_item is unspecified. Use theworkbooks.get() orworkbooks.get_by_id() methods to retrieve the workbook item from the server. |
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('username','password',site_id='site')server=TSC.Server('https://servername')withserver.auth.sign_in(tableau_auth):# get the workbook item from the siteworkbook=server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')# call the update methodworkbook=server.workbooks.refresh(workbook)print("\nThe data of workbook {0} is refreshed.".format(workbook.name))workbooks.update(workbook_item)Modifies an existing workbook. Use this method to change the owner or the project that the workbook belongs to, or to change whether the workbook shows views in tabs. The workbook item must include the workbook ID and overrides the existing settings.
REST API:Update Workbooks
Parameters
| Name | Description |
|---|---|
workbook_item | Theworkbook_item specifies the settings for the workbook you are updating. You can change theowner_id,project_id, and theshow_tabs values. SeeWorkbookItem. |
Exceptions
| Error | Description |
|---|---|
Workbook item missing ID. Workbook must be retrieved from server first. | Raises an error if theworkbook_item is unspecified. Use theworkbooks.get() orworkbooks.get_by_id() methods to retrieve the workbook item from the server. |
importtableauserverclientasTSCtableau_auth=TSC.TableauAuth('username','password',site_id='site')server=TSC.Server('https://servername')withserver.auth.sign_in(tableau_auth):# get the workbook item from the siteworkbook=server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')print("\nUpdate {0} workbook. Project was {1}".format(workbook.name,workbook.project_name))# make an change, for example a new project IDworkbook.project_id='1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e'# call the update methodworkbook=server.workbooks.update(workbook)print("\nUpdated {0} workbook. Project is now {1}".format(workbook.name,workbook.project_name))workbooks.delete(workbook_id)Deletes a workbook with the specified ID.
To specify the site, create aTableauAuth instance using the content URL for the site (site_id), and sign in to that site. See theTableauAuth class.
REST API:Delete Workbook
Parameters
| Name | Description |
|---|---|
workbook_id | The ID of the workbook to delete. |
Exceptions
| Error | Description |
|---|---|
Workbook 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')# tableau_auth sign in, etc.server.workbooks.delete('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')workbooks.download(workbook_id,filepath=None,no_extract=False)Downloads a workbook to the specified directory (optional).
REST API:Download Workbook
Parameters
| Name | Description |
|---|---|
workbook_id | The ID for theWorkbookItem that you want to download from the server. |
filepath | (Optional) Downloads the file to the location you specify. If no location is specified, the file is downloaded to the current working directory. The default isFilepath=None. |
no_extract | (Optional) Specifies whether to download the file without the extract. When the workbook has an extract, if you set the parameterno_extract=True, the extract is not included. You can use this parameter to improve performance if you are downloading workbooks that have large extracts. The default is to include the extract, if present (no_extract=False). Available starting with Tableau Server REST API version 2.5. |
Exceptions
| Error | Description |
|---|---|
Workbook ID undefined | Raises an exception if a validdatasource_id is not provided. |
Returns
The file path to the downloaded workbook.
Example
file_path=server.workbooks.download('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')print("\nDownloaded the file to {0}.".format(file_path))workbooks.populate_views(workbook_item)Populates (or gets) a list of views for a workbook.
You must first call this method to populate views before you can iterate through the views.
This method retrieves the view information for the specified workbook. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the view information is not included. Use this method to retrieve the views. The method adds the list of views to the workbook item (workbook_item.views). This is a list ofViewItem.
REST API:Query Views for Workbook
Parameters
| Name | Description |
|---|---|
workbook_item | Theworkbook_item specifies the workbook to populate with views information. SeeWorkbookItem class. |
Exceptions
| Error | Description |
|---|---|
Workbook item missing ID. Workbook must be retrieved from server first. | Raises an error if theworkbook_item is unspecified. You can retrieve the workbook items using theworkbooks.get() andworkbooks.get_by_id() methods. |
Returns
None. A list ofViewItem objects are added to the workbook (workbook_item.views).
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVERURL')#...# get the workbook itemworkbook=server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')# get the view informationserver.workbooks.populate_views(workbook)# print information about the views for the work itemprint("\nThe views for {0}: ".format(workbook.name))print([view.nameforviewinworkbook.views])...workbooks.populate_connections(workbook_item)Populates a list of data source connections for the specified workbook.
You must populate connections before you can iterate through theconnections.
This method retrieves the data source connection information for the specified workbook. The REST API is designed to return only the information you ask for explicitly. When you query all the workbooks, the data source connection information is not included. Use this method to retrieve the connection information for any data sources used by the workbook. The method adds the list of data connections to the workbook item (workbook_item.connections). This is a list ofConnectionItem.
REST API:Query Workbook Connections
Parameters
| Name | Description |
|---|---|
workbook_item | Theworkbook_item specifies the workbook to populate with data connection information. |
Exceptions
| Error | Description |
|---|---|
Workbook item missing ID. Workbook must be retrieved from server first. | Raises an error if theworkbook_item is unspecified. |
Returns
None. A list ofConnectionItem objects are added to the data source (workbook_item.connections).
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVERURL')#...# get the workbook itemworkbook=server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')# get the connection informationserver.workbooks.populate_connections(workbook)# print information about the data connections for the workbook itemprint("\nThe connections for {0}: ".format(workbook.name))print([connection.idforconnectioninworkbook.connections])...workbooks.populate_preview_image(workbook_item)This method gets the preview image (thumbnail) for the specified workbook item.
The method uses theview.id andworkbook.id to identify the preview image. The method populates theworkbook_item.preview_image.
REST API:Query View Preview Image
Parameters
| Name | Description |
|---|---|
view_item | The view item specifies theview.id andworkbook.id that identifies the preview image. |
Exceptions
| Error | Description |
|---|---|
View item missing ID or workbook ID | Raises an error if the ID for the view item or workbook is missing. |
Returns
None. The preview image is added to the view.
Example
# import tableauserverclient as TSC# server = TSC.Server('https://SERVERURL')...# get the workbook itemworkbook=server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')# add the png thumbnail to the workbook itemserver.workbooks.populate_preview_image(workbook)workbooks.update_connection(workbook_item,connection_item)Updates a workbook connection information (server address, server port, user name, and password).
The workbook connections must be populated before the strings can be updated. Seeworkbooks.populate_connections
REST API:Update Workbook Connection
Parameters
| Name | Description |
|---|---|
workbook_item | Theworkbook_item specifies the workbook to populate with data connection information. |
connection_item | Theconnection_item that has the information you want to update. |
Returns
None. The connection information is updated with the information in theConnectionItem.
Example
# query for workbook connectionsserver.workbooks.populate_connections(workbook)# update connection item user name and passwordconnection=workbook.connections[0]connection.username='USERNAME'connection.password='PASSWORD'# call the update methodserver.workbooks.update_connection(workbook,connection)workbooks.populate_pdf(workbook_item, req_options=None)Populates the PDF content of the specified workbook.
This method populates a PDF with image(s) of the workbook view(s) you specify.
REST API:Download Workbook PDF
Version
This endpoint is available with REST API version 3.4 and up.
Parameters
| Name | description |
|---|---|
workbook_item | Specifies the workbook 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. SeePDFRequestOptions class for more details. |
Exceptions
| Error | Description |
|---|---|
Workbook item missing ID | Raises an error if the ID of the workbook is missing. |
Returns
None. The PDF content is added to theworkbook_item and can be accessed by itspdf field.
Example
# Sign in, get view, etc.# Populate and save the workbook pdf as 'workbook_pdf.pdf'server.workbooks.populate_pdf(workbook_item)withopen('./workbook_pdf.pdf','wb')asf:f.write(workbook_item.pdf)