API reference

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 Online resources programmatically. You can use this library to create your own custom applications.

The TSC API reference is organized by resource. The TSC library is modeled after the REST API. The methods, for example, workbooks.get(), correspond to the endpoints for resources, such as workbooks, users, views, and data sources. The model classes (for example, the WorkbookItem class have attributes that represent the fields (name, id, owner_id) that are in the REST API request and response packages, or payloads.

• Authentication
  • TableauAuth class
  • Auth methods
    • auth.sign in
    • auth.sign out
• Connections
  • ConnectionItem class
  • ConnectionCredentials class
• Data sources
  • DatasourceItem class
  • Datasources methods
    • datasources.delete
    • datasources.download
    • datasources.get
    • datasources.get_by_id
    • datasources.populate_connections
    • datasources.publish
    • datasources.update
• Filters
  • Filter class
• Groups
  • GroupItem class
  • Groups methods
    • groups.add_user
    • groups.create
    • groups.delete
    • groups.get
    • groups.populate_users
    • groups.remove_user
• Projects
  • ProjectItem class
    • ProjectItem.ContentPermissions
  • Project methods
    • projects.create
    • projects.get
    • projects.update
    • projects.delete
• Requests
  • RequestOptions class
    • RequestOptions.Field class
    • RequestOptions.Operator class
    • RequestOptions.Direction class
• Server
  • Server class
    • Server.Resources
    • Server.PublishMode
  • ServerInfoItem class
  • ServerInfo methods
    • server_info.get
• Sites
  • SiteItem class
  • Site methods
    • sites.create
    • sites.get
    • sites.get_by_id
    • sites.get_by_name
    • sites.update
    • sites.delete
• Sort
  • Sort class
• Users
  • UserItem class
  • Users methods
    • users.add
    • users.get
    • users.get_by_id
    • users.populate_favorites
    • users.populate_workbooks
    • users.remove
    • users.update
• Views
  • ViewItem class
  • Views methods
    • views.get
    • views.populate_preview_image
• Workbooks
  • WorkbookItem class
  • Workbook methods
    • workbooks.get
    • workbooks.get_by_id
    • workbooks.publish
    • workbooks.update
    • workbooks.delete
    • workbooks.download
    • workbooks.populate_views
    • workbooks.populate_connections
    • workbooks.populate_preview_image
    • workbooks.update_connection

Authentication

You can use the TSC library to sign in and sign out of Tableau Server and Tableau Online. The credentials for signing in are defined in the TableauAuth class and they correspond to the attributes you specify when you sign in using the Tableau Server REST API.

TableauAuth class

TableauAuth(username, password, site_id='', user_id_to_impersonate=None)

The TableauAuth class defines the information you can set in a sign-in request. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the Auth.sign_in method.

Note: In the future, there might be support for additional forms of authorization and authentication (for example, OAuth).

Attributes

Source file: models/tableau_auth.py

Example

import tableauserverclient as TSC
# create a new instance of a TableauAuth object for authentication

tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')

# create a server instance
# pass the "tableau_auth" object to the server.auth.sign_in() method

Auth methods

The Tableau Server Client provides two methods for interacting with authentication resources. These methods correspond to the sign in and sign out endpoints in the Tableau Server REST API.

Source file: server/endpoint/auth_endpoint.py

auth.sign in

auth.sign_in(auth_req)

Signs you in to Tableau Server.

The method signs into Tableau Server or Tableau Online and manages the authentication token. You call this method from the server object you create. For information about the server object, see Server. The authentication token keeps you signed in for 240 minutes, or until you call the auth.sign_out method. Before you use this method, you first need to create the sign-in request (auth_req) object by creating an instance of the TableauAuth. To call this method, create a server object for your server. For more information, see Sign in and Out.

REST API: Sign In

Parameters

auth_req : The TableauAuth object that holds the sign-in credentials for the site.

Example

import tableauserverclient as TSC

# create an auth object
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')

# create an instance for your server
server = TSC.Server('http://SERVER_URL')

# call the sign-in method with the auth object
server.auth.sign_in(tableau_auth)

See Also
Sign in and Out
Server

auth.sign out

auth.sign_out()

Signs you out of the current session.

The sign_out() method takes care of invalidating the authentication token. For more information, see Sign in and Out.

REST API: Sign Out

Example

server.auth.sign_out()

See Also
Sign in and Out
Server

Connections

The connections for Tableau Server data sources and workbooks are represented by a ConnectionItem class. You can call data source and workbook methods to query or update the connection information. The ConnectionCredentials class represents the connection information you can update.

ConnectionItem class

ConnectionItem()

The ConnectionItem class corresponds to workbook and data source connections.

In the Tableau Server REST API, there are separate endpoints to query and update workbook and data source connections.

Attributes

Source file: models/connection_item.py

ConnectionCredentials class

ConnectionCredentials(name, password, embed=True, oauth=False)

The ConnectionCredentials class is used for workbook and data source publish requests.

Attributes

Source file: models/connection_credentials.py

Data sources

Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project. The data source resources for Tableau Server are defined in the DatasourceItem class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about the name of the data source, its type, its connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the DatasourceItem class.

DatasourceItem class

DatasourceItem(project_id, name=None)

The DatasourceItem represents the data source resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for data sources. When you create a new DatasourceItem instance, you must specify the project_id that the data source is associated with.

Attributes

Example

    import tableauserverclient as TSC

    # Create new datasource_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39'

    new_datasource = TSC.DatasourceItem('3a8b6148-493c-11e6-a621-6f3499394a39')

Source file: models/datasource_item.py

Datasources methods

The Tableau Server Client provides several methods for interacting with data source resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.

Source file: server/endpoint/datasources_endpoint.py

datasources.delete

datasources.delete(datasource_id)

Removes the specified data source from Tableau Server.

Parameters

Exceptions

REST API: Delete Datasource

datasources.download

datasources.download(datasource_id, filepath=None, no_extract=False)

Downloads the specified data source in .tdsx format.

REST API: Download Datasource

Parameters

Exceptions

Returns

The file path to the downloaded data source. The data source is downloaded in .tdsx format.

Example

  file_path = server.datasources.download('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
  print("\nDownloaded the file to {0}.".format(file_path))

datasources.get

datasources.get(req_options=None)

Returns all the data sources for the site.

To get the connection information for each data source, you must first populate the DatasourceItem with connection information using the populate_connections(datasource_item) method. For more information, see Populate Connections and Views

REST API: Query Datasources

Parameters

Returns

Returns a list of DatasourceItem objects and a PaginationItem object. Use these values to iterate through the results.

Example

import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
server = TSC.Server('http://SERVERURL')

with server.auth.sign_in(tableau_auth):
    all_datasources, pagination_item = server.datasources.get()
    print("\nThere are {} datasources on site: ".format(pagination_item.total_available))
    print([datasource.name for datasource in all_datasources])

datasources.get_by_id

datasources.get_by_id(datasource_id)

Returns the specified data source item.

REST API: Query Datasource

Parameters

Exceptions

Returns

The DatasourceItem. See DatasourceItem class

Example

datasource = server.datasources.get_by_id('59a57c0f-3905-4022-9e87-424fb05e9c0e')
print(datasource.name)

datasources.populate_connections

datasources.populate_connections(datasource_item)

Populates the connections for the specified data source.

This method retrieves the connection information for the specified data source. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the connection information is not included. Use this method to retrieve the connections. The method adds the list of data connections to the data source item (datasource_item.connections). This is a list of ConnectionItem objects.

REST API: Query Datasource Connections

Parameters

Exceptions

Returns

None. A list of ConnectionItem objects are added to the data source (datasource_item.connections).

Example

# import tableauserverclient as TSC

# server = TSC.Server('http://SERVERURL')
# 
   ... 

# get the data source
  datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')


# get the connection information 
  server.datasources.populate_connections(datasource)

# print the information about the first connection item
  print(datasource.connections[0].connection_type)
  print(datasource.connections[0].id)
  print(datasource.connections[0].server_address)

  ...

datasources.publish

datasources.publish(datasource_item, file_path, mode, connection_credentials=None)

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 opeation.

REST API: Publish Datasource

Parameters

Exceptions

Returns

The DatasourceItem for the data source that was added or appended to.

Example

  import tableauserverclient as TSC
  server = TSC.Server('http://SERVERURL')
    
  ...

  project_id = '3a8b6148-493c-11e6-a621-6f3499394a39'
  file_path = r'C:\temp\WorldIndicators.tde'
  

  # Use the project id to create new datsource_item
  new_datasource = TSC.DatasourceItem(project_id)

  # publish data source (specified in file_path)
  new_datasource = server.datasources.publish(
                    new_datasource, file_path, 'CreateNew')

    ...

datasources.update

datasource.update(datasource_item)

Updates the owner, or project of the specified data source.

REST API: Update Datasource

Parameters

Exceptions

Returns

An updated DatasourceItem.

Example

# import tableauserverclient as TSC
# server = TSC.Server('http://SERVERURL')
# sign in ...   
  
# get the data source item to update
  datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
  
# do some updating 
  datasource.name = 'New Name'

# call the update method with the data source item
  updated_datasource = server.datasources.update(datasource)

Filters

The TSC library provides a Filter class that you can use to filter results returned from the server.

You can use the Filter and RequestOptions classes to filter and sort the following endpoints:

• Users
• Datasources
• Workbooks
• Views

For more information, see Filter and Sort.

Filter class

Filter(field, operator, value)

The Filter class corresponds to the filter expressions in the Tableau REST API.

Attributes

Groups

Using the TSC library, you can get information about all the groups on a site, you can add or remove groups, or add or remove users in a group.

The group resources for Tableau Server are defined in the GroupItem class. The class corresponds to the group resources you can access using the Tableau Server REST API. The group methods are based upon the endpoints for groups in the REST API and operate on the GroupItem class.

GroupItem class

GroupItem(name)

The GroupItem class contains the attributes for the group resources on Tableau Server. The GroupItem class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.

Source file: models/group_item.py

Attributes

Example

 newgroup = TSC.GroupItem('My Group')

 # call groups.create() with new group

Groups methods

The Tableau Server Client provides several methods for interacting with group resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.

Source file: server/endpoint/groups_endpoint.py

groups.add_user

groups.add_user(group_item, user_id):

Adds a user to the specified group.

REST API Add User to Group

Parameters

Returns

None.

Example

# Adding a user to a group
# 
# get the group item
  all_groups, pagination_item = server.groups.get()
  mygroup = all_groups[1]

# The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba'

# add Ian to the group
  server.groups.add_user(mygroup, '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba')

groups.create

create(group_item)

Creates a new group in Tableau Server.

REST API: Create Group

Parameters

Returns Adds new GroupItem.

Example

# Create a new group

#  import tableauserverclient as TSC
#  tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
#  server = TSC.Server('http://SERVERURL')


# create a new instance with the group name
  newgroup = TSC.GroupItem('My Group')

# call the create method
  newgroup = server.groups.create(newgroup)

# print the names of the groups on the server
  all_groups, pagination_item = server.groups.get()
  for group in all_groups :
      print(group.name, group.id)

groups.delete

groups.delete(group_id)

Deletes the group on the site.

REST API: Delete Group

Parameters

Exceptions

Example

#  Delete a group from the site

# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('http://SERVERURL')

  with server.auth.sign_in(tableau_auth):
     server.groups.delete('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')

groups.get

groups.get(req_options=None)

Returns information about the groups on the site.

To get information about the users in a group, you must first populate the GroupItem with user information using the groups.populate_users method.

REST API: Get Uers on Site

Parameters

Returns

Returns a list of GroupItem objects and a PaginationItem object. Use these values to iterate through the results.

Example

# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('http://SERVERURL')

  with server.auth.sign_in(tableau_auth):

       # get the groups on the server
       all_groups, pagination_item = server.groups.get()

       # print the names of the first 100 groups
       for group in all_groups :
           print(group.name, group.id)

groups.populate_users

groups.populate_users(group_item, req_options=None)

Populates the group_item with the list of users.

REST API: Get Users in Group

Parameters

Exceptions

Group item missing ID. Group must be retrieved from server first. : Raises an error if the group_item is unspecified.

Returns

None. A list of UserItem objects are added to the group (group_item.users).

Example

# import tableauserverclient as TSC

# server = TSC.Server('http://SERVERURL')
# 
   ... 

# get the group
  all_groups, pagination_item = server.groups.get()
  mygroup = all_groups[1]

# get the user information 
  pagination_item = server.groups.populate_users(mygroup)


# print the names of the users
  for user in mygroup.users :
        print(user.name) 
  

groups.remove_user

groups.remove_user(group_item, user_id)

Removes a user from a group.

REST API: Remove User from Group

Parameters

Exceptions

Returns

None. The user is removed from the group.

Example

#  Remove a user from the group

# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
# server = TSC.Server('http://SERVERURL')

  with server.auth.sign_in(tableau_auth):

     # get the group
     mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')

     # remove user '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d'
     server.groups.remove_user(mygroup, '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')

Projects

Using the TSC library, you can get information about all the projects on a site, or you can create, update projects, or remove projects.

The project resources for Tableau are defined in the ProjectItem class. The class corresponds to the project resources you can access using the Tableau Server REST API. The project methods are based upon the endpoints for projects in the REST API and operate on the ProjectItem class.

ProjectItem class

ProjectItem(name, description=None, content_permissions=None)

The project resources for Tableau are defined in the ProjectItem class. The class corresponds to the project resources you can access using the Tableau Server REST API.

Attributes

Source file: models/project_item.py

ProjectItem.ContentPermissions

The ProjectItem class has a sub-class that defines the permissions for the project (ProjectItem.ContentPermissions). The options are LockedToProject and ManagedByOwner. For information on these content permissions, see Lock Content Permissions to the Project

Example

# import tableauserverclient as TSC
# server = TSC.Server('http://MY-SERVER')
# sign in, etc


locked_true = TSC.ProjectItem.ContentPermissions.LockedToProject
print(locked_true)
# prints 'LockedToProject'

by_owner = TSC.ProjectItem.ContentPermissions.ManagedByOwner
print(by_owner)
# prints 'ManagedByOwner'


# pass the content_permissions to new instance of the project item. 
new_project = TSC.ProjectItem(name='My Project', content_permissions=by_owner, description='Project example')

Project methods

The project methods are based upon the endpoints for projects in the REST API and operate on the ProjectItem class.

Source files: server/endpoint/projects_endpoint.py

projects.create

projects.create(project_item)

Creates a project on the specified site.

To create a project, you first create a new instance of a ProjectItem and pass it to the create method. To specify the site to create the new project, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.

REST API: Create Project

Parameters

Returns Returns the new project item.

Example

import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
server = TSC.Server('http://SERVER')

with server.auth.sign_in(tableau_auth): 
    # create project item
    new_project = TSC.ProjectItem(name='Example Project', content_permissions='LockedToProject', description='Project created for testing')
    # create the project 
    new_project = server.projects.create(new_project)

projects.get

projects.get()  

Return a list of project items for a site.

To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.

REST API: Query Projects

Parameters

None.

Returns

Returns a list of all ProjectItem objects and a PaginationItem. Use these values to iterate through the results.

Example

import tableauserverclient as TSC  
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')  
server = TSC.Server('http://SERVER')  

with server.auth.sign_in(tableau_auth): 
        # get all projects on site
        all_project_items, pagination_item = server.projects.get()
        print([proj.name for proj in all_project_items])

projects.update

projects.update(project_item)

Modify the project settings.

You can use this method to update the project name, the project description, or the project permissions. To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.

REST API: Update Project

Parameters

Exceptions

Returns

Returns the updated project information.

See ProjectItem class

Example

# import tableauserverclient as TSC
# server = TSC.Server('http://MY-SERVER')
# sign in, etc

  ...
  # get list of projects
  all_project_items, pagination_item = server.projects.get()
  

  # update project item #7 with new name, etc.
  my_project = all_projects[7]
  my_project.name ='New name'
  my_project.description = 'New description'      
  
  # call method to update project      
  updated_project = server.projects.update(my_project)
 

  

projects.delete

projects.delete(project_id)

Deletes a project by ID.

To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.

REST API: Delete Project

Parameters

Exceptions

Example

# import tableauserverclient as TSC  
# server = TSC.Server('http://MY-SERVER')  
# sign in, etc.  

 server.projects.delete('1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e')

Requests

The TSC library provides a RequestOptions class that you can use to filter results returned from the server.

You can use the Sort and RequestOptions classes to filter and sort the following endpoints:

• Users
• Datasources
• Groups
• Workbooks
• Views

For more information, see Filter and Sort.

RequestOptions class

RequestOptions(pagenumber=1, pagesize=100)

Attributes

RequestOptions.Field class

The RequestOptions.Field class corresponds to the fields used in filter expressions in the Tableau REST API. For more information, see Filtering and Sorting in the Tableau REST API.

Attributes

Attributes

RequestOptions.Operator class

Specifies the operators you can use to filter requests.

Attributes

RequestOptions.Direction class

Specifies the direction to sort the returned fields.

Attributes

Server

In the Tableau REST API, the server (http://MY-SERVER/) is the base or core of the URI that makes up the various endpoints or methods for accessing resources on the server (views, workbooks, sites, users, data sources, etc.) The TSC library provides a Server class that represents the server. You create a server instance to sign in to the server and to call the various methods for accessing resources.

Server class

Server(server_address)

The Server class contains the attributes that represent the server on Tableau Server. After you create an instance of the Server class, you can sign in to the server and call methods to access all of the resources on the server.

Attributes

Example

import tableauserverclient as TSC

# create a instance of server 
server = TSC.Server('http://MY-SERVER')


# change the REST API version to 2.5
server.version = '2.5'  

Server.Resources

When you create an instance of the Server class, you have access to the resources on the server after you sign in. You can select these resources and their methods as members of the class, for example: server.views.get()

Server.PublishMode

The Server class has PublishMode class that enumerates the options that specify what happens when you publish a workbook or data source. The options are Overwrite, Append, or CreateNew.

Properties

Example

 
 print(TSC.Server.PublishMode.Overwrite)
 # prints 'Overwrite'
 
 overwrite_true = TSC.Server.PublishMode.Overwrite

 ...

 # pass the PublishMode to the publish workbooks method
 new_workbook = server.workbooks.publish(new_workbook, args.filepath, overwrite_true)

ServerInfoItem class

ServerInfoItem(product_version, build_number, rest_api_version)

The ServerInfoItem class contains the build and version information for Tableau Server. The server information is accessed with the server_info.get() method, which returns an instance of the ServerInfo class.

Attributes

ServerInfo methods

The TSC library provides a method to access the build and version information from Tableau Server.

server_info.get

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

Example

import tableauserverclient as TSC

# create a instance of server 
server = TSC.Server('http://MY-SERVER')

# set the version number > 2.3 
# the server_info.get() method works in 2.4 and later
server.version = '2.5'

s_info = server.server_info.get()
print("\nServer info:")
print("\tProduct version: {0}".format(s_info.product_version))
print("\tREST API version: {0}".format(s_info.rest_api_version))
print("\tBuild number: {0}".format(s_info.build_number))

Sites

Using the TSC library, you can query a site or sites on a server, or create or delete a site on the server.

The site resources for Tableau Server and Tableau Online are defined in the SiteItem class. The class corresponds to the site resources you can access using the Tableau Server REST API. The site methods are based upon the endpoints for sites in the REST API and operate on the SiteItem class.

SiteItem class

SiteItem(name, content_url, admin_mode=None, user_quota=None, storage_quota=None,
                 disable_subscriptions=False, subscribe_others_enabled=True, revision_history_enabled=False)

The SiteItem class contains the members or attributes for the site resources on Tableau Server or Tableau Online. The SiteItem class defines the information you can request or query from Tableau Server or Tableau Online. The class members correspond to the attributes of a server request or response payload.

Attributes

Example

# create a new instance of a SiteItem

new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode='ContentAndUsers', user_quota=15, storage_quota=1000, disable_subscriptions=True)

Source file: models/site_item.py

Site methods

The TSC library provides methods that operate on sites for Tableau Server and Tableau Online. These methods correspond to endpoints or methods for sites in the Tableau REST API.

Source file: server/endpoint/sites_endpoint.py

sites.create

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

Returns

Returns a new instance of SiteItem.

Example

import tableauserverclient as TSC

# create an instance of server 
server = TSC.Server('http://MY-SERVER')

# create shortcut for admin mode
content_users=TSC.SiteItem.AdminMode.ContentAndUsers

# create a new SiteItem
new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode=content_users, user_quota=15, storage_quota=1000, disable_subscriptions=True)

# call the sites create method with the SiteItem
new_site = server.sites.create(new_site)

sites.get

sites.get()

Queries all the sites on the server.

REST API: Query Sites

Parameters

None.

Returns

Returns a list of all SiteItem objects and a PaginationItem. Use these values to iterate through the results.

Example

# import tableauserverclient as TSC
# server = TSC.Server('http://MY-SERVER')
# sign in, etc.

  # query the sites
  all_sites, pagination_item = server.sites.get()

  # print all the site names and ids
  for site in TSC.Pager(server.sites):
       print(site.id, site.name, site.content_url, site.state)

sites.get_by_id

sites.get_by_id(site_id)

Queries the site with the given ID.

REST API: Query Site

Parameters

Exceptions

Returns

Returns the SiteItem.

Example

# import tableauserverclient as TSC
# server = TSC.Server('http://MY-SERVER')
# sign in, etc.

 a_site = server.sites.get_by_id('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')
 print("\nThe site with id '9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d' is: {0}".format(a_site.name)) 

sites.get_by_name

sites.get_by_name(site_name)

Queries the site with the specified name.

REST API: Query Site

Parameters

Exceptions

Returns

Returns the SiteItem.

Example

# import tableauserverclient as TSC
# server = TSC.Server('http://MY-SERVER')
# sign in, etc.

 a_site = server.sites.get_by_name('MY_SITE')

sites.update

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

Exceptions

Returns

Returns the updated site_item.

Example

...

# make some updates to an existing site_item
site_item.name ="New name"

# call update
site_item = server.sites.update(site_item)

...

sites.delete

Sites.delete(site_id)

Deletes the specified site.

REST API: Delete Site

Parameters

Exceptions

Example

# import tableauserverclient as TSC
# server = TSC.Server('http://MY-SERVER')
# sign in, etc.

server.sites.delete('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')

Sort

The Sort class is used with request options (RequestOptions) where you can filter and sort on the results returned from the server.

You can use the sort and request options to filter and sort the following endpoints:

• Users
• Datasources
• Workbooks
• Views

Sort class

sort(field, direction)

Attributes

Example

# create a new instance of a request option object
req_option = TSC.RequestOptions()

# add the sort expression, sorting by name and direction
req_option.sort.add(TSC.Sort(TSC.RequestOptions.Field.Name,
                             TSC.RequestOptions.Direction.Asc))
matching_workbooks, pagination_item = server.workbooks.get(req_option)

for wb in matching_workbooks:
    print(wb.name)

For information about using the Sort class, see Filter and Sort.

Users

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 the UserItem 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 the UserItem class.

UserItem class

UserItem(name, site_role, auth_setting=None)

The UserItem class contains the members or attributes for the view resources on Tableau Server. The UserItem 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

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

Users methods

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

users.add(user_item)

Adds the user to the site.

To add a new user to the site you need to first create a new user_item (from UserItem class). When you create a new user, you specify the name of the user and their site role. For Tableau Online, you also specify the auth_setting attribute in your request. When you add user to Tableau Online, the name of the user must be the email address that is used to sign in to Tableau Online. After you add a user, Tableau Online 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

Returns

Returns the new UserItem 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 site
  newU = server.users.add(newU)
  print(newU.name, newU.site_role)

users.get

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 the UserItem with workbook information using the populate_workbooks(user_item) method.

REST API: Get Users on Site

Parameters

Returns

Returns a list of UserItem objects and a PaginationItem object. Use these values to iterate through the results.

Example

import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
server = TSC.Server('http://SERVERURL')

with server.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.name for user in all_users])

users.get_by_id

users.get_by_id(user_id)

Returns information about the specified user.

REST API: Query User On Site

Parameters

Exceptions

Returns

The UserItem. See UserItem class

Example

  user1 = server.users.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
  print(user1.name)

users.populate_favorites

users.populate_favorites(user_item)

Returns the list of favorites (views, workbooks, and data sources) for a user.

Not currently implemented

users.populate_workbooks

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 Datasource Connections

Parameters

Exceptions

Returns

A list of WorkbookItem

A PaginationItem that points (user_item.workbooks). See UserItem 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:")
  for workbook in all_users[0].workbooks :
      print(workbook.name)

    ...

users.remove

users.remove(user_id)    

Removes the specified user from the site.

REST API: Remove User from Site

Parameters

Exceptions

Example

#  Remove a user from the site

#  import tableauserverclient as TSC
#  tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
#  server = TSC.Server('http://SERVERURL')

   with server.auth.sign_in(tableau_auth):
     server.users.remove('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')

users.update

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 Online, and whether you have configured Tableau Server to use local authentication or Active Directory. For more information, see Update User.

REST API: Update User

Parameters

Exceptions

Returns

An updated UserItem. See UserItem class

Example

#  import tableauserverclient as TSC
#  tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
#  server = TSC.Server('http://SERVERURL')

 with server.auth.sign_in(tableau_auth):
    
  # create a new user_item
    user1 = TSC.UserItem('temp', 'Viewer')
     
  # add new user
    user1 = server.users.add(user1)
    print(user1.name, user1.site_role, user1.id)

  # modify user info
    user1.name = 'Laura'
    user1.fullname = 'Laura Rodriguez'
    user1.email = 'laura@example.com'
 
  # update user
    user1 = server.users.update(user1)
    print("\Updated user info:")
    print(user1.name, user1.fullname, user1.email, user1.id)

Views

Using the TSC library, you can get all the views on a site, or get the views for a workbook, or populate a view with preview images. The view resources for Tableau Server are defined in the ViewItem class. The class corresponds to the view resources you can access using the Tableau Server REST API, for example, you can find the name of the view, its id, and the id of the workbook it is associated with. The view methods are based upon the endpoints for views in the REST API and operate on the ViewItem class.

ViewItem class

class ViewItem(object)
 

The ViewItem class contains the members or attributes for the view resources on Tableau Server. The ViewItem 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

Views methods

The Tableau Server Client provides two 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

views.get(req_option=None)

Returns the list of views items for a site.

REST API: Query Views for Site

Parameters

Returns

Returns a list of all ViewItem objects and a PaginationItem. Use these values to iterate through the results.

Example

import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('username', 'password')
server = TSC.Server('http://servername')

with server.auth.sign_in(tableau_auth):
  all_views, pagination_item = server.views.get()
  print([view.name for view in all_views])

See ViewItem class

views.populate_preview_image

 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 the view.id and workbook.id to identify the preview image. The method populates the view.preview_image for the view.

REST API: Query View Preview Image

Parameters

Exceptions

Returns

None. The preview image is added to the view.

See ViewItem class

Workbooks

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 the WorkbookItem 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 the WorkbookItem class.

WorkbookItem class

 
 WorkbookItem(project_id, name=None, show_tabs=False)
 

The workbook resources for Tableau are defined in the WorkbookItem class. The class corresponds to the workbook resources you can access using the Tableau REST API. Some workbook methods take an instance of the WorkbookItem class as arguments. The workbook item specifies the project

Attributes

Example

# creating a new instance of a WorkbookItem
# 
import tableauserverclient as TSC

# 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

Workbook methods

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

workbooks.get(req_options=None)

Queries the server and returns information about the workbooks the site.

REST API: Query Workbooks for Site

Parameters

Returns

Returns a list of all WorkbookItem objects and a PaginationItem. Use these values to iterate through the results.

Example

import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('username', 'password', site_id='site')
server = TSC.Server('http://servername')

with server.auth.sign_in(tableau_auth):
  all_workbook_items, pagination_item = server.workbooks.get()
  print([workbook.name for workbook in all_workbooks])

workbooks.get_by_id

workbooks.get_by_id(workbook_id)

Returns information about the specified workbook on the site.

REST API: Query Workbook

Parameters

Exceptions

Returns

The WorkbookItem. See WorkbookItem class

Example

workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')
print(workbook.name)

workbooks.publish

workbooks.publish(workbook_item, file_path, publish_mode) 

Publish a workbook to the specified site.

Note: The REST API cannot automatically include extracts 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

Exceptions

See the REST API Publish Workbook for additional error codes.

Returns

The WorkbookItem for the workbook that was published.

Example

import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('username', 'password', site_id='site')
server = TSC.Server('http://servername')

with server.auth.sign_in(tableau_auth):
   # create a workbook item
   wb_item = TSC.WorkbookItem(name='Sample', project_id='1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e')
   # call the publish method with the workbook item
   wb_item = server.workbooks.publish(wb_item, 'SampleWB.twbx', 'Overwrite')

workbooks.update

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

Exceptions

import tableauserverclient as TSC
tableau_auth = TSC.TableauAuth('username', 'password', site_id='site')
server = TSC.Server('http://servername')

with server.auth.sign_in(tableau_auth):

    # get the workbook item from the site
    workbook = 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 ID
    workbook.project_id = '1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e'

    # call the update method
    workbook = server.workbooks.update(workbook)
    print("\nUpdated {0} workbook. Project is now {1}".format(workbook.name, workbook.project_name))

workbooks.delete

workbooks.delete(workbook_id)

Deletes a workbook with the specified ID.

To specify the site, create a TableauAuth instance using the content URL for the site (site_id), and sign in to that site. See the TableauAuth class.

REST API: Delete Workbook

Parameters

Exceptions

Example

# import tableauserverclient as TSC  
# server = TSC.Server('http://MY-SERVER')  
# tableau_auth sign in, etc.  

 server.workbooks.delete('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')

workbooks.download

workbooks.download(workbook_id, filepath=None, no_extract=False)

Downloads a workbook to the specified directory (optional).

REST API: Download Workbook

Parameters

Exceptions

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

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 of ViewItem.

REST API: Query Views for Workbook

Parameters

Exceptions

Returns

None. A list of ViewItem objects are added to the workbook (workbook_item.views).

Example

# import tableauserverclient as TSC

# server = TSC.Server('http://SERVERURL')
# 
   ... 

# get the workbook item
  workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')


# get the view information 
  server.workbooks.populate_views(workbook)

# print information about the views for the work item
  print("\nThe views for {0}: ".format(workbook.name))
  print([view.name for view in workbook.views])

  ...

workbooks.populate_connections

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 the connections.

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 of ConnectionItem.

REST API: Query Workbook Connections

Parameters

Exceptions

Returns

None. A list of ConnectionItem objects are added to the data source (workbook_item.connections).

Example

# import tableauserverclient as TSC

# server = TSC.Server('http://SERVERURL')
# 
   ... 

# get the workbook item
  workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')


# get the connection information 
  server.workbooks.populate_connections(workbook)

# print information about the data connections for the workbook item
  print("\nThe connections for {0}: ".format(workbook.name))
  print([connection.id for connection in workbook.connections])


  ...

workbooks.populate_preview_image

workbooks.populate_preview_image(workbook_item)

This method gets the preview image (thumbnail) for the specified workbook item.

The method uses the view.id and workbook.id to identify the preview image. The method populates the workbook_item.preview_image.

REST API: Query View Preview Image

Parameters

Exceptions

Returns

None. The preview image is added to the view.

Example

# import tableauserverclient as TSC

# server = TSC.Server('http://SERVERURL')

   ... 

  # get the workbook item
  workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d')

  # add the png thumbnail to the workbook item
  server.workbooks.populate_preview_image(workbook)

workbooks.update_connection

workbooks.update_conn(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. See workbooks.populate_connections

REST API: Update Workbook Connection

Parameters

Returns

None. The connection information is updated with the information in the ConnectionItem.

Example

# update connection item user name and password
workbook.connections[0].username = 'USERNAME'
workbook.connections[0].password = 'PASSWORD'

# call the update method
server.workbooks.update_conn(workbook, workbook.connections[0])