diff --git a/_includes/docs_menu.html b/_includes/docs_menu.html
index 6ed9e1721..6ed1a381d 100644
--- a/_includes/docs_menu.html
+++ b/_includes/docs_menu.html
@@ -52,6 +52,9 @@
Data Sources
+
+ Databases
+
Favorites
@@ -94,6 +97,9 @@
Subscriptions
+
+ Tables
+
Tasks
diff --git a/docs/api-ref.md b/docs/api-ref.md
index 104213764..05defcd6e 100644
--- a/docs/api-ref.md
+++ b/docs/api-ref.md
@@ -1966,7 +1966,7 @@ datasources.delete_dqw(datasource_item)
Removes all data quality warnings from the specified data source.
-REST API: [Delete Quality Warning Triggers by Content](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_dqw_triggers)
+REST API: [Delete Data Quality Warning by Content](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_dqws)
**Parameters**
@@ -2448,115 +2448,178 @@ for ds in certified_ds:
---
-## Favorites
+## Databases
-Using the TSC library, you can get, add, and remove favorites for a user. Favorites can be workbooks, views, datasources, flows, projects, or metrics.
+Using the TSC library, you can get information about the database assets on a site, update a database's description, certification, and contact, and manage its permissions, data quality warnings, and tags. Database assets are external assets that Tableau Catalog discovers from the connections used by published content. The database resources are defined in the `DatabaseItem` class, and the methods are based upon the database endpoints in the REST API.
-The favorites for a user are stored as a dictionary on the `UserItem` object. The dictionary is keyed by content type (`"workbooks"`, `"views"`, `"datasources"`, `"flows"`, `"projects"`, `"metrics"`, `"collections"`) and each value is a list of the corresponding item objects.
+Database and table methods are available if your Tableau Cloud site or Tableau Server is licensed with Data Management. See the [Metadata Methods](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm){:target="_blank"} in the REST API reference.
+
+
+
+### DatabaseItem class
+
+```py
+DatabaseItem(name, description=None, content_permissions=None)
+```
+
+The `DatabaseItem` represents a database asset on Tableau Server or Tableau Cloud. Database items are normally returned by the server from `databases.get` or `databases.get_by_id` rather than created directly.
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`certification_note` | The certification note for the database. Settable; sent to the server by `databases.update`.
+`certified` | `True` if the database is certified. Settable (must be a boolean); sent to the server by `databases.update`.
+`connection_type` | The connection type of the database, for example `sqlserver` or `hyper`. Read-only.
+`connector_url` | The connector URL of the database. Read-only.
+`contact_id` | The ID of the user who is the contact for the database. Settable; sent to the server by `databases.update`.
+`content_permissions` | The permission mode of the database, as returned by the server. Must be one of `DatabaseItem.ContentPermissions.LockedToProject` (value `"LockedToDatabase"`) or `DatabaseItem.ContentPermissions.ManagedByOwner` (value `"ManagedByOwner"`). Can be set on the object, and `databases.update` sends it to the server.
+`default_table_permissions` | The default permissions for tables in the database, as a list of `PermissionsRule` objects. You must first call `databases.populate_table_default_permissions` to access this data.
+`description` | The description of the database. Settable; sent to the server by `databases.update`. An empty string clears the description.
+`dqws` | The list of data quality warnings (`DQWItem`) for the database. You must first call `databases.populate_dqw` to access this data.
+`embedded` | `True` if the database is embedded in Tableau content. Read-only.
+`file_extension` | The file extension, for file-based databases. Read-only.
+`file_id` | The file ID, for file-based databases. Read-only.
+`file_path` | The file path, for file-based databases. Read-only.
+`host_name` | The host name of the database server. Read-only.
+`id` | The identifier (LUID) of the database. Read-only.
+`metadata_type` | The asset type of the database, from the `type` attribute in the server response. Read-only.
+`mime_type` | The MIME type, for file-based databases. Read-only.
+`name` | The name of the database. Must not be empty. `databases.update` does not send the name to the server.
+`permissions` | The permissions for the database, as a list of `PermissionsRule` objects. You must first call `databases.populate_permissions` to access this data.
+`port` | The port of the database server, as an integer. Read-only.
+`provider` | The provider of the database. Read-only.
+`request_url` | The request URL of the database. Read-only.
+`tables` | The tables in the database. The tables are not available through `databases.populate_tables`, which is not supported (see [databases.populate_tables](#databasespopulate_tables)). Accessing this property raises `UnpopulatedPropertyError`.
+
+**Example**
+
+```py
+import tableauserverclient as TSC
+
+# sign in, etc.
+
+database = server.databases.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+print(database.name, database.connection_type, database.host_name, database.port)
+```
+
+Source file: models/database_item.py
-### Favorites methods
+### Databases methods
-The Tableau Server Client provides several methods for interacting with favorites. These methods correspond to endpoints in the Tableau Server REST API.
+The Tableau Server Client provides several methods for interacting with database assets. These methods correspond to endpoints in the Tableau Server REST API.
-Source file: server/endpoint/favorites_endpoint.py
+Source file: server/endpoint/databases_endpoint.py
-#### favorites.get
+#### databases.get
```py
-favorites.get(user_item, req_options=None)
+databases.get(req_options=None)
```
-Populates the favorites for the specified user. After calling this method, the favorites are available through `user_item.favorites`.
+Returns one page of the database assets on the site. The server returns 100 items per page by default. To iterate over every database on the site, use `TSC.Pager(server.databases)`.
-REST API: [Get Favorites for User](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#get_favorites_for_user)
+REST API: [Query Databases](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_databases){:target="_blank"}
**Version**
-This endpoint is available with REST API version 2.5 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` for which to retrieve favorites.
-`req_options` | (Optional) Request options such as page size and page number.
+`req_options` | (Optional) A `RequestOptions` object to set the page size and page number of the request.
**Returns**
-None. Favorites are populated on `user_item.favorites`.
+Returns a list of `DatabaseItem` objects and a `PaginationItem` object.
**Example**
```py
-server.favorites.get(user_item)
-for workbook in user_item.favorites['workbooks']:
- print(workbook.name)
+all_databases, pagination_item = server.databases.get()
+print("There are {} databases on site.".format(pagination_item.total_available))
+print([database.name for database in all_databases])
+
+for database in TSC.Pager(server.databases):
+ print(database.id, database.name)
```
-#### favorites.add_favorite
+#### databases.get_by_id
```py
-favorites.add_favorite(user_item, content_type, item)
+databases.get_by_id(database_id)
```
-Adds a content item of any supported type to the specified user's favorites.
+Returns the specified database asset.
-REST API: [Add Workbook to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_workbook_to_favorites)
+REST API: [Query Database](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_database){:target="_blank"}
**Version**
-This endpoint is available with REST API version 3.15 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to add the favorite for.
-`content_type` | The type of content as a string (e.g., `"workbook"`, `"view"`, `"datasource"`, `"flow"`, `"project"`).
-`item` | The content item to favorite. Must have `id` and `name` attributes.
+`database_id` | The identifier (`id`) of the database to return.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`ValueError` | Raised if `database_id` is empty or `None`.
**Returns**
-Returns the server `Response` object.
+Returns a `DatabaseItem`.
**Example**
```py
-server.favorites.add_favorite(user_item, 'workbook', workbook_item)
+database = server.databases.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+print(database.name)
```
-#### favorites.add_favorite_workbook
+#### databases.delete
```py
-favorites.add_favorite_workbook(user_item, workbook_item)
+databases.delete(database_id)
```
-Adds a workbook to the specified user's favorites.
+Permanently removes the specified database asset.
-REST API: [Add Workbook to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_workbook_to_favorites)
+REST API: [Remove Database](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#remove_database){:target="_blank"}
**Version**
-This endpoint is available with REST API version 2.0 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to add the favorite for.
-`workbook_item` | The `WorkbookItem` to add to favorites.
+`database_id` | The identifier (`id`) of the database to remove.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`ValueError` | Raised if `database_id` is empty or `None`.
**Returns**
@@ -2565,134 +2628,186 @@ None.
**Example**
```py
-server.favorites.add_favorite_workbook(user_item, workbook_item)
+server.databases.delete('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
```
-#### favorites.add_favorite_view
+#### databases.update
```py
-favorites.add_favorite_view(user_item, view_item)
+databases.update(database_item)
```
-Adds a view to the specified user's favorites.
+Updates the description, certification, certification note, and contact of the specified database.
-REST API: [Add View to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_view_to_favorites)
+Only the values that are set on `database_item` are sent. A value of `None` leaves the matching property unchanged on the server, and an empty string for `description` or `certification_note` clears it. The `certified`, `description`, `certification_note`, `content_permissions`, and `contact_id` values can be updated. The `name` value is not sent.
+
+REST API: [Update Database](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_database){:target="_blank"}
**Version**
-This endpoint is available with REST API version 2.0 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to add the favorite for.
-`view_item` | The `ViewItem` to add to favorites.
+`database_item` | The `DatabaseItem` to update. It must have an `id`, so retrieve it from the server first.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`MissingRequiredFieldError` | Raised if `database_item` does not have an `id`.
**Returns**
-None.
+Returns the updated `DatabaseItem`.
**Example**
```py
-server.favorites.add_favorite_view(user_item, view_item)
+database = server.databases.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+database.description = 'Sales data warehouse'
+database.certified = True
+database.certification_note = 'Reviewed by the data team'
+database = server.databases.update(database)
```
-#### favorites.add_favorite_datasource
+#### databases.populate_tables
```py
-favorites.add_favorite_datasource(user_item, datasource_item)
+databases.populate_tables(database_item)
```
-Adds a datasource to the specified user's favorites.
+This method is not supported. Calling it always raises `NotImplementedError`, because the REST API does not have an endpoint that lists the tables in a database.
-REST API: [Add Data Source to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_data_source_to_favorites)
+To find the tables in a database, query the Metadata API with [metadata.query](#metadataquery) and read the matching tables with `tables.get_by_id`. The `explore_databases_tables.py` sample shows this approach.
+
+**Example**
+
+```py
+query = """
+query tablesInDatabase($luid: String) {
+ databases(filter: {luid: $luid}) {
+ tables { luid name }
+ }
+}
+"""
+result = server.metadata.query(query, {'luid': database.id})
+for table_ref in result['data']['databases'][0]['tables']:
+ table = server.tables.get_by_id(table_ref['luid'])
+ print(table.name)
+```
+
+
+
+
+#### databases.populate_permissions
+
+```py
+databases.populate_permissions(item)
+```
+
+Populates the permissions for the specified database. After calling this method, the permissions are available through `item.permissions`.
+
+REST API: [List Database Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_database_perms){:target="_blank"}
**Version**
-This endpoint is available with REST API version 2.3 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to add the favorite for.
-`datasource_item` | The `DatasourceItem` to add to favorites.
+`item` | The `DatabaseItem` to populate with permissions.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`MissingRequiredFieldError` | Raised if `item` does not have an `id`.
**Returns**
-None.
+None. Permissions are populated on `item.permissions`.
**Example**
```py
-server.favorites.add_favorite_datasource(user_item, datasource_item)
+database = server.databases.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+server.databases.populate_permissions(database)
+for rule in database.permissions:
+ print(rule.grantee.tag_name, rule.grantee.id, rule.capabilities)
```
-#### favorites.add_favorite_project
+#### databases.update_permissions
```py
-favorites.add_favorite_project(user_item, project_item)
+databases.update_permissions(item, rules)
```
-Adds a project to the specified user's favorites.
+Adds permissions to the specified database.
-REST API: [Add Project to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_project_to_favorites)
+REST API: [Add Database Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#add_database_perms){:target="_blank"}
**Version**
-This endpoint is available with REST API version 3.1 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to add the favorite for.
-`project_item` | The `ProjectItem` to add to favorites.
+`item` | The `DatabaseItem` to add permissions to.
+`rules` | A list of `PermissionsRule` objects to add.
**Returns**
-None.
+Returns the list of `PermissionsRule` objects in the server response.
**Example**
```py
-server.favorites.add_favorite_project(user_item, project_item)
+rule = TSC.PermissionsRule(
+ grantee=TSC.GroupItem.as_reference('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d'),
+ capabilities={TSC.Permission.Capability.Read: TSC.Permission.Mode.Allow},
+)
+server.databases.update_permissions(database, [rule])
```
-#### favorites.add_favorite_flow
+#### databases.delete_permission
```py
-favorites.add_favorite_flow(user_item, flow_item)
+databases.delete_permission(item, rules)
```
-Adds a flow to the specified user's favorites.
+Removes permissions from the specified database. For each rule, every capability in `rule.capabilities` is removed for `rule.grantee` with a separate request.
-REST API: [Add Flow to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_flow_to_favorites)
+REST API: [Delete Database Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_database_perms){:target="_blank"}
**Version**
-This endpoint is available with REST API version 3.3 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to add the favorite for.
-`flow_item` | The `FlowItem` to add to favorites.
+`item` | The `DatabaseItem` to remove permissions from.
+`rules` | A list of `PermissionsRule` objects to remove. A single `PermissionsRule` is also accepted.
**Returns**
@@ -2701,97 +2816,112 @@ None.
**Example**
```py
-server.favorites.add_favorite_flow(user_item, flow_item)
+server.databases.populate_permissions(database)
+server.databases.delete_permission(database, database.permissions[:1])
```
-#### favorites.add_favorite_metric
+#### databases.populate_table_default_permissions
```py
-favorites.add_favorite_metric(user_item, metric_item)
+databases.populate_table_default_permissions(item)
```
-Adds a metric to the specified user's favorites.
+Populates the default permissions that apply to tables in the specified database. After calling this method, the permissions are available through `item.default_table_permissions`.
+
+REST API: [List Default Database Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_database_perms_default){:target="_blank"}
**Version**
-This endpoint is available with REST API version 3.3 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to add the favorite for.
-`metric_item` | The `MetricItem` to add to favorites.
+`item` | The `DatabaseItem` to populate with default table permissions.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`MissingRequiredFieldError` | Raised if `item` does not have an `id`.
**Returns**
-None.
+None. Permissions are populated on `item.default_table_permissions`.
**Example**
```py
-server.favorites.add_favorite_metric(user_item, metric_item)
+server.databases.populate_table_default_permissions(database)
+for rule in database.default_table_permissions:
+ print(rule.grantee.tag_name, rule.grantee.id, rule.capabilities)
```
-#### favorites.delete_favorite
+#### databases.update_table_default_permissions
```py
-favorites.delete_favorite(user_item, content_type, item)
+databases.update_table_default_permissions(item, rules)
```
-Removes a content item of any supported type from the specified user's favorites.
+Adds default permissions for tables in the specified database.
+
+REST API: [Add Default Database Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#add_database_perms_default){:target="_blank"}
**Version**
-This endpoint is available with REST API version 3.15 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to remove the favorite from.
-`content_type` | The `Resource` type of the content (e.g., `Resource.Workbook`, `Resource.View`).
-`item` | The content item to remove from favorites. Must have an `id` attribute.
+`item` | The `DatabaseItem` to add default table permissions to.
+`rules` | A list of `PermissionsRule` objects to add.
**Returns**
-None.
+Returns the list of `PermissionsRule` objects in the server response.
**Example**
```py
-server.favorites.delete_favorite(user_item, Resource.Workbook, workbook_item)
+rule = TSC.PermissionsRule(
+ grantee=TSC.GroupItem.as_reference('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d'),
+ capabilities={TSC.Permission.Capability.Read: TSC.Permission.Mode.Allow},
+)
+server.databases.update_table_default_permissions(database, [rule])
```
-#### favorites.delete_favorite_workbook
+#### databases.delete_table_default_permissions
```py
-favorites.delete_favorite_workbook(user_item, workbook_item)
+databases.delete_table_default_permissions(item, rule)
```
-Removes a workbook from the specified user's favorites.
+Removes a default table permission rule from the specified database. Every capability in `rule.capabilities` is removed for `rule.grantee` with a separate request. Passing the arguments in the order `(rule, item)` still works but emits a `DeprecationWarning`.
-REST API: [Delete Workbook from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_workbook_from_favorites)
+REST API: [Delete Default Database Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_database_perms_default){:target="_blank"}
**Version**
-This endpoint is available with REST API version 2.0 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to remove the favorite from.
-`workbook_item` | The `WorkbookItem` to remove from favorites.
+`item` | The `DatabaseItem` to remove the default table permission from.
+`rule` | A single `PermissionsRule` to remove.
**Returns**
@@ -2800,134 +2930,149 @@ None.
**Example**
```py
-server.favorites.delete_favorite_workbook(user_item, workbook_item)
+server.databases.populate_table_default_permissions(database)
+rule = database.default_table_permissions[0]
+server.databases.delete_table_default_permissions(database, rule)
```
-#### favorites.delete_favorite_view
+#### databases.populate_dqw
```py
-favorites.delete_favorite_view(user_item, view_item)
+databases.populate_dqw(item)
```
-Removes a view from the specified user's favorites.
+Populates the data quality warnings for the specified database. After calling this method, the warnings are available through `item.dqws`.
-REST API: [Delete View from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_view_from_favorites)
+REST API: [Query Data Quality Warning by Content](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_dqws){:target="_blank"}
**Version**
-This endpoint is available with REST API version 2.0 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to remove the favorite from.
-`view_item` | The `ViewItem` to remove from favorites.
+`item` | The `DatabaseItem` to populate with data quality warnings.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`MissingRequiredFieldError` | Raised if `item` does not have an `id`.
**Returns**
-None.
+None. Warnings are populated on `item.dqws`.
**Example**
```py
-server.favorites.delete_favorite_view(user_item, view_item)
+server.databases.populate_dqw(database)
+for dqw in database.dqws:
+ print(dqw.warning_type, dqw.message)
```
-#### favorites.delete_favorite_datasource
+#### databases.add_dqw
```py
-favorites.delete_favorite_datasource(user_item, datasource_item)
+databases.add_dqw(item, warning)
```
-Removes a datasource from the specified user's favorites.
+Adds a data quality warning to the specified database.
-REST API: [Delete Data Source from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_data_source_from_favorites)
+REST API: [Add Data Quality Warning](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#add_dqw){:target="_blank"}
**Version**
-This endpoint is available with REST API version 2.3 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to remove the favorite from.
-`datasource_item` | The `DatasourceItem` to remove from favorites.
+`item` | The `DatabaseItem` to add the warning to.
+`warning` | The `DQWItem` to add.
**Returns**
-None.
+Returns the list of `DQWItem` objects in the server response.
**Example**
```py
-server.favorites.delete_favorite_datasource(user_item, datasource_item)
+warning = TSC.DQWItem(warning_type=TSC.DQWItem.WarningType.MAINTENANCE, message='Scheduled maintenance this weekend')
+server.databases.add_dqw(database, warning)
```
-#### favorites.delete_favorite_project
+#### databases.update_dqw
```py
-favorites.delete_favorite_project(user_item, project_item)
+databases.update_dqw(item, warning)
```
-Removes a project from the specified user's favorites.
+Updates the data quality warning on the specified database.
-REST API: [Delete Project from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_project_from_favorites)
+The request is sent as a `PUT` to `/dataQualityWarnings/database/{database-id}`, using the ID of `item`. The `id` of `warning` is not used. The REST API reference documents Update Data Quality Warning as a `PUT` to `/dataQualityWarnings/{warning-id}`, so check the result against your server.
+
+REST API: [Update Data Quality Warning](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_dqw){:target="_blank"}
**Version**
-This endpoint is available with REST API version 3.1 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to remove the favorite from.
-`project_item` | The `ProjectItem` to remove from favorites.
+`item` | The `DatabaseItem` whose warning to update.
+`warning` | The `DQWItem` with the updated values.
**Returns**
-None.
+Returns the list of `DQWItem` objects in the server response.
**Example**
```py
-server.favorites.delete_favorite_project(user_item, project_item)
+server.databases.populate_dqw(database)
+warning = database.dqws[0]
+warning.message = 'Maintenance complete'
+warning.active = False
+server.databases.update_dqw(database, warning)
```
-#### favorites.delete_favorite_flow
+#### databases.delete_dqw
```py
-favorites.delete_favorite_flow(user_item, flow_item)
+databases.delete_dqw(item)
```
-Removes a flow from the specified user's favorites.
+Removes the data quality warnings from the specified database.
-REST API: [Delete Flow from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_flow_from_favorites)
+REST API: [Delete Data Quality Warning by Content](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_dqws){:target="_blank"}
**Version**
-This endpoint is available with REST API version 3.3 and up.
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to remove the favorite from.
-`flow_item` | The `FlowItem` to remove from favorites.
+`item` | The `DatabaseItem` to remove the warnings from.
**Returns**
@@ -2936,2061 +3081,2009 @@ None.
**Example**
```py
-server.favorites.delete_favorite_flow(user_item, flow_item)
+server.databases.delete_dqw(database)
```
-#### favorites.delete_favorite_metric
+#### databases.add_tags
```py
-favorites.delete_favorite_metric(user_item, metric_item)
+databases.add_tags(item, tags)
```
-Removes a metric from the specified user's favorites.
+Adds one or more tags to the specified database.
+
+REST API: [Add Tags to Database](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#add_tags_database){:target="_blank"}
**Version**
-This endpoint is available with REST API version 3.15 and up.
+This endpoint is available with REST API version 3.9 and up.
**Parameters**
Name | Description
:--- | :---
-`user_item` | The `UserItem` to remove the favorite from.
-`metric_item` | The `MetricItem` to remove from favorites.
+`item` | The `DatabaseItem` or database ID to add tags to.
+`tags` | A single tag string or an iterable of tag strings to add.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`ValueError` | Raised if `item` is not a database ID string and has no `id`.
**Returns**
-None.
+Returns a `set[str]` of the tags in the server response.
**Example**
```py
-server.favorites.delete_favorite_metric(user_item, metric_item)
+server.databases.add_tags(database, ['finance', 'quarterly'])
```
----
-
-## 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-sort).
-
-
-### Filter class
+#### databases.delete_tags
```py
-Filter(field, operator, value)
+databases.delete_tags(item, tags)
```
-The `Filter` class corresponds to the *filter expressions* in the Tableau REST API.
+Removes one or more tags from the specified database. Each tag is removed with a separate request.
+REST API: Delete Tag from Database, in the [Metadata Methods](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm){:target="_blank"} reference.
+**Version**
-**Attributes**
+This endpoint is available with REST API version 3.9 and up.
+
+**Parameters**
Name | Description
:--- | :---
-`Field` | Defined in the `RequestOptions.Field` class.
-`Operator` | Defined in the `RequestOptions.Operator` class
-`Value` | The value to compare with the specified field and operator.
+`item` | The `DatabaseItem` or database ID to remove tags from.
+`tags` | A single tag string or an iterable of tag strings to remove.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`ValueError` | Raised if `item` is not a database ID string and has no `id`.
+**Returns**
+None.
+**Example**
+```py
+server.databases.delete_tags(database, 'quarterly')
+```
----
-
-## Flows
-
-Using the TSC library, you can get information about all the flows on a site, or get information about a specific flow. The flow resources for Tableau Server are defined in the `FlowItem` class. The class corresponds to the flow resources you can access using the Tableau Server REST API. The flow methods are based upon the endpoints for flows in the REST API and operate on the `FlowItem` class.
-
-
-
-### FlowItem class
+#### databases.update_tags
```py
-FlowItem(project_id, name=None)
+databases.update_tags(item)
```
-The `FlowItem` represents the flow resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for flows. When you create a new `FlowItem` instance, you must specify the `project_id` that the flow is associated with.
+Not supported for databases. `DatabaseItem` does not track a tag set. On REST API 3.8 and earlier, this method raises `EndpointUnavailableError`. On later versions, it raises `NotImplementedError`. Use `databases.add_tags` and `databases.delete_tags` instead.
-**Attributes**
+**Version**
-Name | Description
-:--- | :---
-`connections` | The list of data connections (`ConnectionItem`) for the specified flow. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class).
-`created_at` | The date and time when the flow was created.
-`description` | The description for the flow.
-`dqws` | The list of data quality warnings for the flow. You must first call `populate_dqw` to access this data.
-`id` | The identifier for the flow. You need this value to query a specific flow or to delete a flow with the `get_by_id` and `delete` methods.
-`name` | The name of the flow. If not specified when publishing, the name of the published flow file is used.
-`owner_id` | The identifier of the owner of the flow.
-`permissions` | The permissions for the flow. You must first call `populate_permissions` to access this data.
-`project_id` | The identifier of the project associated with the flow. You must provide this identifier when you create an instance of a `FlowItem`.
-`project_name` | The name of the project associated with the flow.
-`tags` | The tags (set of strings) that have been added to the flow.
-`updated_at` | The date and time when the flow was last updated.
-`webpage_url` | The URL of the flow as displayed in browsers.
+The method is gated on REST API version 3.9, so on earlier versions it raises `EndpointUnavailableError` instead.
-**Example**
+
+
-```py
-import tableauserverclient as TSC
+## Favorites
-# Create new flow_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39'
-new_flow = TSC.FlowItem('3a8b6148-493c-11e6-a621-6f3499394a39')
-```
+Using the TSC library, you can get, add, and remove favorites for a user. Favorites can be workbooks, views, datasources, flows, projects, or metrics.
-Source file: models/flow_item.py
+The favorites for a user are stored as a dictionary on the `UserItem` object. The dictionary is keyed by content type (`"workbooks"`, `"views"`, `"datasources"`, `"flows"`, `"projects"`, `"metrics"`, `"collections"`) and each value is a list of the corresponding item objects.
-### Flows methods
+### Favorites methods
-The Tableau Server Client provides several methods for interacting with flow resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
+The Tableau Server Client provides several methods for interacting with favorites. These methods correspond to endpoints in the Tableau Server REST API.
-Source file: server/endpoint/flows_endpoint.py
+Source file: server/endpoint/favorites_endpoint.py
-#### flows.delete
+#### favorites.get
```py
-flows.delete(flow_id)
+favorites.get(user_item, req_options=None)
```
-Removes the specified flow from Tableau Server.
+Populates the favorites for the specified user. After calling this method, the favorites are available through `user_item.favorites`.
-REST API: [Delete Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#delete_flow){:target="_blank"}
+REST API: [Get Favorites for User](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#get_favorites_for_user)
+
+**Version**
+
+This endpoint is available with REST API version 2.5 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_id` | The identifier (`id`) for the `FlowItem` that you want to delete from the server.
+`user_item` | The `UserItem` for which to retrieve favorites.
+`req_options` | (Optional) Request options such as page size and page number.
-**Exceptions**
+**Returns**
-Error | Description
-:--- | :---
-`Flow ID undefined` | Raises an exception if a valid `flow_id` is not provided.
+None. Favorites are populated on `user_item.favorites`.
-**Version**
+**Example**
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+```py
+server.favorites.get(user_item)
+for workbook in user_item.favorites['workbooks']:
+ print(workbook.name)
+```
-#### flows.download
+#### favorites.add_favorite
```py
-flows.download(flow_id, filepath=None)
+favorites.add_favorite(user_item, content_type, item)
```
-Downloads the specified flow in `.tfl` or `.tflx` format.
+Adds a content item of any supported type to the specified user's favorites.
-REST API: [Download Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#download_flow){:target="_blank"}
+REST API: [Add Workbook to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_workbook_to_favorites)
-**Parameters**
+**Version**
-Name | Description
-:--- | :---
-`flow_id` | The identifier (`id`) for the `FlowItem` that you want to download from the server.
-`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `filepath=None`), the file is downloaded to the current working directory.
+This endpoint is available with REST API version 3.15 and up.
-**Exceptions**
+**Parameters**
-Error | Description
+Name | Description
:--- | :---
-`Flow ID undefined` | Raises an exception if a valid `flow_id` is not provided.
+`user_item` | The `UserItem` to add the favorite for.
+`content_type` | The type of content as a string (e.g., `"workbook"`, `"view"`, `"datasource"`, `"flow"`, `"project"`).
+`item` | The content item to favorite. Must have `id` and `name` attributes.
**Returns**
-The file path to the downloaded flow.
-
-**Version**
-
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+Returns the server `Response` object.
**Example**
```py
-file_path = server.flows.download('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-print("\nDownloaded the file to {0}.".format(file_path))
+server.favorites.add_favorite(user_item, 'workbook', workbook_item)
```
-#### flows.get
+#### favorites.add_favorite_workbook
```py
-flows.get(req_options=None)
+favorites.add_favorite_workbook(user_item, workbook_item)
```
-Returns all the flows for the site.
+Adds a workbook to the specified user's favorites.
-To get the connection information for each flow, you must first populate the `FlowItem` with connection information using the [flows.populate_connections](#flowspopulate_connections) method.
+REST API: [Add Workbook to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_workbook_to_favorites)
-REST API: [Query Flows for Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flows_for_site){:target="_blank"}
+**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 flow, you could specify the name of the project or its id.
+`user_item` | The `UserItem` to add the favorite for.
+`workbook_item` | The `WorkbookItem` to add to favorites.
**Returns**
-Returns a list of `FlowItem` objects and a `PaginationItem` object. Use these values to iterate through the results.
-
-**Version**
-
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-import tableauserverclient as TSC
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-server = TSC.Server('https://SERVERURL')
-
-with server.auth.sign_in(tableau_auth):
- all_flows, pagination_item = server.flows.get()
- print("\nThere are {} flows on site: ".format(pagination_item.total_available))
- print([flow.name for flow in all_flows])
+server.favorites.add_favorite_workbook(user_item, workbook_item)
```
-#### flows.get_by_id
+#### favorites.add_favorite_view
```py
-flows.get_by_id(flow_id)
+favorites.add_favorite_view(user_item, view_item)
```
-Returns the specified flow item.
+Adds a view to the specified user's favorites.
-REST API: [Query Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow){:target="_blank"}
+REST API: [Add View to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_view_to_favorites)
-**Parameters**
+**Version**
-Name | Description
-:--- | :---
-`flow_id` | The `flow_id` specifies the flow to query.
+This endpoint is available with REST API version 2.0 and up.
-**Exceptions**
+**Parameters**
-Error | Description
+Name | Description
:--- | :---
-`Flow ID undefined` | Raises an exception if a valid `flow_id` is not provided.
+`user_item` | The `UserItem` to add the favorite for.
+`view_item` | The `ViewItem` to add to favorites.
**Returns**
-Returns a `FlowItem`.
-
-**Version**
-
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-print(flow.name)
+server.favorites.add_favorite_view(user_item, view_item)
```
-#### flows.populate_connections
+#### favorites.add_favorite_datasource
```py
-flows.populate_connections(flow_item)
+favorites.add_favorite_datasource(user_item, datasource_item)
```
-Populates a `FlowItem` with connection information.
+Adds a datasource to the specified user's favorites.
-This method retrieves the connection information for the specified flow. The method requires a `FlowItem` object and populates its `connections` property with a list of `ConnectionItem` objects. You must call this method before you can access the `connections` property of a `FlowItem`.
+REST API: [Add Data Source to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_data_source_to_favorites)
-REST API: [Query Flow Connections](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow_connections){:target="_blank"}
+**Version**
+
+This endpoint is available with REST API version 2.3 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `flow_item` specifies the flow to populate with connection information.
-
-**Exceptions**
-
-Error | Description
-:--- | :---
-`Flow item missing ID. Flow must be retrieved from server first.` | Raises an exception if the `flow_item` does not have an id. The `flow_item` must be retrieved from the server first.
+`user_item` | The `UserItem` to add the favorite for.
+`datasource_item` | The `DatasourceItem` to add to favorites.
-**Version**
+**Returns**
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-server.flows.populate_connections(flow)
-for connection in flow.connections:
- print(connection.id)
+server.favorites.add_favorite_datasource(user_item, datasource_item)
```
-#### flows.publish
+#### favorites.add_favorite_project
```py
-flows.publish(flow_item, file, mode, connections=None)
+favorites.add_favorite_project(user_item, project_item)
```
-Publishes a flow to Tableau Server.
+Adds a project to the specified user's favorites.
-REST API: [Publish Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#publish_flow){:target="_blank"}
+REST API: [Add Project to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_project_to_favorites)
-**Parameters**
+**Version**
-Name | Description
-:--- | :---
-`flow_item` | The `flow_item` specifies the flow you are publishing. The `flow_item` must have a `project_id` set.
-`file` | The file path or file object of the flow to publish. Only `.tfl` and `.tflx` files are supported.
-`mode` | Specifies whether you are publishing a new flow (`CreateNew`), or overwriting an existing one (`Overwrite`). You cannot use `Append` with flows.
-`connections` | (Optional) A list of `ConnectionItem` objects for connections in the flow that require credentials.
+This endpoint is available with REST API version 3.1 and up.
-**Exceptions**
+**Parameters**
-Error | Description
+Name | Description
:--- | :---
-`Invalid mode defined.` | Raises an error if the mode specified is not valid.
-`File path does not lead to an existing file.` | Raises an error if the file path specified does not point to a valid file.
-`Only .tfl, .tflx files can be published as flows.` | Raises an error if the type of file specified is not supported.
+`user_item` | The `UserItem` to add the favorite for.
+`project_item` | The `ProjectItem` to add to favorites.
**Returns**
-Returns a `FlowItem` representing the published flow.
-
-**Version**
-
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-import tableauserverclient as TSC
-
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
-server = TSC.Server('https://SERVERURL')
-
-with server.auth.sign_in(tableau_auth):
- project_id = 'cc867571-b4e0-4764-8083-84b9f3aa8543'
- new_flow = TSC.FlowItem(project_id)
- new_flow = server.flows.publish(new_flow, 'path/to/flow.tflx', TSC.Server.PublishMode.Overwrite)
- print("Published flow ID: {0}".format(new_flow.id))
+server.favorites.add_favorite_project(user_item, project_item)
```
-#### flows.refresh
+#### favorites.add_favorite_flow
```py
-flows.refresh(flow_item)
+favorites.add_favorite_flow(user_item, flow_item)
```
-Runs the specified flow and returns a `JobItem` to track the progress of the run.
+Adds a flow to the specified user's favorites.
-REST API: [Run Flow Now](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#run_flow_now){:target="_blank"}
+REST API: [Add Flow to Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#add_flow_to_favorites)
+
+**Version**
+
+This endpoint is available with REST API version 3.3 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `FlowItem` to run.
+`user_item` | The `UserItem` to add the favorite for.
+`flow_item` | The `FlowItem` to add to favorites.
**Returns**
-Returns a `JobItem`. Use the `jobs.wait_for_job` method to block until the job is complete.
+None.
-**Version**
-
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-
-**Example**
+**Example**
```py
-flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-job = server.flows.refresh(flow)
-server.jobs.wait_for_job(job)
+server.favorites.add_favorite_flow(user_item, flow_item)
```
-#### flows.update
+#### favorites.add_favorite_metric
```py
-flows.update(flow_item)
+favorites.add_favorite_metric(user_item, metric_item)
```
-Modifies an existing flow. Use this method to change the owner or project of a flow, or to update its tags.
+Adds a metric to the specified user's favorites.
-REST API: [Update Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#update_flow){:target="_blank"}
+**Version**
+
+This endpoint is available with REST API version 3.3 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `FlowItem` with updated attributes. Must have been retrieved from the server (must have an `id`).
-
-**Exceptions**
-
-Error | Description
-:--- | :---
-`Flow item missing ID. Flow must be retrieved from server first.` | Raises an exception if the `flow_item` does not have an id.
+`user_item` | The `UserItem` to add the favorite for.
+`metric_item` | The `MetricItem` to add to favorites.
**Returns**
-Returns the updated `FlowItem`.
-
-**Version**
-
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-flow.project_id = 'new-project-id'
-updated_flow = server.flows.update(flow)
+server.favorites.add_favorite_metric(user_item, metric_item)
```
-#### flows.update_connection
+#### favorites.delete_favorite
```py
-flows.update_connection(flow_item, connection_item)
+favorites.delete_favorite(user_item, content_type, item)
```
-Updates the server address, port, username, or password for the specified flow connection.
+Removes a content item of any supported type from the specified user's favorites.
-REST API: [Update Flow Connection](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#update_flow_connection){:target="_blank"}
+**Version**
+
+This endpoint is available with REST API version 3.15 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `FlowItem` to update.
-`connection_item` | The `ConnectionItem` with updated attributes.
+`user_item` | The `UserItem` to remove the favorite from.
+`content_type` | The `Resource` type of the content (e.g., `Resource.Workbook`, `Resource.View`).
+`item` | The content item to remove from favorites. Must have an `id` attribute.
**Returns**
-Returns the updated `ConnectionItem`.
-
-**Version**
-
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-server.flows.populate_connections(flow)
-connection = flow.connections[0]
-connection.server_address = 'new-server.example.com'
-updated_connection = server.flows.update_connection(flow, connection)
+server.favorites.delete_favorite(user_item, Resource.Workbook, workbook_item)
```
-**Workload Identity Federation (WIF):** setting `connection_item.workgroup_auth_mode` (and, for impersonation, `connection_item.auth_federation_service_account`) emits the matching attributes on the request payload via the shared `Connection.update_req` builder. Server-side handling of WIF on flow connections is governed by the flow endpoint and may differ from workbook and datasource behavior.
-
-#### flows.populate_permissions
+#### favorites.delete_favorite_workbook
```py
-flows.populate_permissions(flow_item)
+favorites.delete_favorite_workbook(user_item, workbook_item)
```
-Populates the permissions for the specified flow.
+Removes a workbook from the specified user's favorites.
+
+REST API: [Delete Workbook from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_workbook_from_favorites)
+
+**Version**
+
+This endpoint is available with REST API version 2.0 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `FlowItem` to populate with permissions.
+`user_item` | The `UserItem` to remove the favorite from.
+`workbook_item` | The `WorkbookItem` to remove from favorites.
-**Version**
+**Returns**
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-server.flows.populate_permissions(flow)
-for permission in flow.permissions:
- print(permission.grantee_id, permission.capabilities)
+server.favorites.delete_favorite_workbook(user_item, workbook_item)
```
-#### flows.update_permissions
+#### favorites.delete_favorite_view
```py
-flows.update_permissions(flow_item, permission_item)
+favorites.delete_favorite_view(user_item, view_item)
```
-Adds or updates permissions for the specified flow.
-
-**Parameters**
+Removes a view from the specified user's favorites.
-Name | Description
-:--- | :---
-`flow_item` | The `FlowItem` to update permissions for.
-`permission_item` | A list of `PermissionsRule` objects representing the permissions to add or update.
+REST API: [Delete View from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_view_from_favorites)
**Version**
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-
-
-
-
-#### flows.delete_permission
-
-```py
-flows.delete_permission(flow_item, capability_item)
-```
-
-Removes a permission from the specified flow.
+This endpoint is available with REST API version 2.0 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `FlowItem` to remove the permission from.
-`capability_item` | The `PermissionsRule` object representing the permission to remove.
+`user_item` | The `UserItem` to remove the favorite from.
+`view_item` | The `ViewItem` to remove from favorites.
-**Version**
+**Returns**
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
+
+**Example**
+
+```py
+server.favorites.delete_favorite_view(user_item, view_item)
+```
-#### flows.populate_dqw
+#### favorites.delete_favorite_datasource
```py
-flows.populate_dqw(flow_item)
+favorites.delete_favorite_datasource(user_item, datasource_item)
```
-Populates the data quality warnings for the specified flow.
+Removes a datasource from the specified user's favorites.
+
+REST API: [Delete Data Source from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_data_source_from_favorites)
+
+**Version**
+
+This endpoint is available with REST API version 2.3 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `FlowItem` to populate with data quality warnings.
+`user_item` | The `UserItem` to remove the favorite from.
+`datasource_item` | The `DatasourceItem` to remove from favorites.
-**Version**
+**Returns**
-Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-server.flows.populate_dqw(flow)
-for dqw in flow.dqws:
- print(dqw.message)
+server.favorites.delete_favorite_datasource(user_item, datasource_item)
```
-#### flows.add_dqw
+#### favorites.delete_favorite_project
```py
-flows.add_dqw(flow_item, warning)
+favorites.delete_favorite_project(user_item, project_item)
```
-Adds a data quality warning to the specified flow.
-
-**Parameters**
+Removes a project from the specified user's favorites.
-Name | Description
-:--- | :---
-`flow_item` | The `FlowItem` to add the data quality warning to.
-`warning` | The `DQWItem` object representing the data quality warning to add.
+REST API: [Delete Project from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_project_from_favorites)
**Version**
-Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-
-
-
-
-#### flows.update_dqw
-
-```py
-flows.update_dqw(flow_item, warning)
-```
-
-Updates a data quality warning on the specified flow.
+This endpoint is available with REST API version 3.1 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `FlowItem` to update the data quality warning on.
-`warning` | The `DQWItem` object representing the updated data quality warning.
+`user_item` | The `UserItem` to remove the favorite from.
+`project_item` | The `ProjectItem` to remove from favorites.
-**Version**
+**Returns**
-Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
+
+**Example**
+
+```py
+server.favorites.delete_favorite_project(user_item, project_item)
+```
-#### flows.delete_dqw
+#### favorites.delete_favorite_flow
```py
-flows.delete_dqw(flow_item)
+favorites.delete_favorite_flow(user_item, flow_item)
```
-Removes all data quality warnings from the specified flow.
+Removes a flow from the specified user's favorites.
+
+REST API: [Delete Flow from Favorites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_favorites.htm#delete_flow_from_favorites)
+
+**Version**
+
+This endpoint is available with REST API version 3.3 and up.
**Parameters**
Name | Description
:--- | :---
-`flow_item` | The `FlowItem` to remove data quality warnings from.
+`user_item` | The `UserItem` to remove the favorite from.
+`flow_item` | The `FlowItem` to remove from favorites.
-**Version**
+**Returns**
-Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
+
+**Example**
+
+```py
+server.favorites.delete_favorite_flow(user_item, flow_item)
+```
-#### flows.schedule_flow_run
+#### favorites.delete_favorite_metric
```py
-flows.schedule_flow_run(schedule_id, item)
+favorites.delete_favorite_metric(user_item, metric_item)
```
-Convenience method to add a flow to an existing schedule.
+Removes a metric from the specified user's favorites.
+
+**Version**
+
+This endpoint is available with REST API version 3.15 and up.
**Parameters**
Name | Description
:--- | :---
-`schedule_id` | The identifier of the schedule to add the flow to.
-`item` | The `FlowItem` to add to the schedule.
+`user_item` | The `UserItem` to remove the favorite from.
+`metric_item` | The `MetricItem` to remove from favorites.
**Returns**
-Returns a list of `AddResponse` objects.
-
-**Version**
-
-Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None.
**Example**
```py
-flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-result = server.flows.schedule_flow_run('schedule-id-here', flow)
+server.favorites.delete_favorite_metric(user_item, metric_item)
```
-#### flows.filter
+---
-```py
-flows.filter(**kwargs)
-```
+## Filters
-Returns a list of flows that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
+The TSC library provides a `Filter` class that you can use to filter results returned from the server.
-**Supported fields and operators**
+You can use the `Filter` and `RequestOptions` classes to filter and sort the following endpoints:
-Field | Operators
-:--- | :---
-`created_at` | `eq`, `gt`, `gte`, `lt`, `lte`
-`name` | `eq`, `in`
-`owner_name` | `eq`
-`project_id` | `eq`
-`project_name` | `eq`, `in`
-`updated` | `eq`, `gt`, `gte`, `lt`, `lte`
+- Users
+- Datasources
+- Workbooks
+- Views
-**Returns**
+For more information, see [Filter and Sort](filter-sort).
-Returns a `QuerySet` of `FlowItem` objects.
-**Example**
+### Filter class
```py
-matching_flows = server.flows.filter(project_name='My Project')
-for flow in matching_flows:
- print(flow.name)
+Filter(field, operator, value)
```
+The `Filter` class corresponds to the *filter expressions* in the Tableau REST API.
+
+
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`Field` | Defined in the `RequestOptions.Field` class.
+`Operator` | Defined in the `RequestOptions.Operator` class
+`Value` | The value to compare with the specified field and operator.
+
+
+
+
+
+
---
-## Flow Runs
-
-Using the TSC library, you can query flow runs on a site, get details about a specific flow run, cancel a running flow, or wait for a flow run to complete. Flow runs are created when a flow is triggered to run, either manually or on a schedule.
+## Flows
-The flow run resources for Tableau Server are defined in the `FlowRunItem` class. The class corresponds to the flow run resources you can access using the Tableau Server REST API.
+Using the TSC library, you can get information about all the flows on a site, or get information about a specific flow. The flow resources for Tableau Server are defined in the `FlowItem` class. The class corresponds to the flow resources you can access using the Tableau Server REST API. The flow methods are based upon the endpoints for flows in the REST API and operate on the `FlowItem` class.
-### FlowRunItem class
+### FlowItem class
-The `FlowRunItem` represents the result of a flow run on Tableau Server. Instances of this class are returned by the flow run methods; you do not create them directly.
+```py
+FlowItem(project_id, name=None)
+```
+
+The `FlowItem` represents the flow resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for flows. When you create a new `FlowItem` instance, you must specify the `project_id` that the flow is associated with.
**Attributes**
Name | Description
:--- | :---
-`id` | The identifier for the flow run.
-`flow_id` | The identifier of the flow that was run.
-`status` | The current status of the flow run. Possible values include `Success`, `Failed`, and `Cancelled`.
-`started_at` | The date and time when the flow run started.
-`completed_at` | The date and time when the flow run completed. Is `None` if the run is still in progress.
-`progress` | The progress percentage of the flow run.
-`background_job_id` | The identifier of the background job associated with the flow run.
+`connections` | The list of data connections (`ConnectionItem`) for the specified flow. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class).
+`created_at` | The date and time when the flow was created.
+`description` | The description for the flow.
+`dqws` | The list of data quality warnings for the flow. You must first call `populate_dqw` to access this data.
+`id` | The identifier for the flow. You need this value to query a specific flow or to delete a flow with the `get_by_id` and `delete` methods.
+`name` | The name of the flow. If not specified when publishing, the name of the published flow file is used.
+`owner_id` | The identifier of the owner of the flow.
+`permissions` | The permissions for the flow. You must first call `populate_permissions` to access this data.
+`project_id` | The identifier of the project associated with the flow. You must provide this identifier when you create an instance of a `FlowItem`.
+`project_name` | The name of the project associated with the flow.
+`tags` | The tags (set of strings) that have been added to the flow.
+`updated_at` | The date and time when the flow was last updated.
+`webpage_url` | The URL of the flow as displayed in browsers.
-Source file: models/flow_run_item.py
+**Example**
+
+```py
+import tableauserverclient as TSC
+
+# Create new flow_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39'
+new_flow = TSC.FlowItem('3a8b6148-493c-11e6-a621-6f3499394a39')
+```
+
+Source file: models/flow_item.py
-### Flow Runs methods
+### Flows methods
-The Tableau Server Client provides several methods for interacting with flow run resources. These methods correspond to endpoints in the Tableau Server REST API.
+The Tableau Server Client provides several methods for interacting with flow resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
-Source file: server/endpoint/flow_runs_endpoint.py
+Source file: server/endpoint/flows_endpoint.py
-#### flow_runs.get
+#### flows.delete
```py
-flow_runs.get(req_options=None)
+flows.delete(flow_id)
```
-Returns all flow runs on the site.
+Removes the specified flow from Tableau Server.
-REST API: [Get Flow Runs](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#get_flow_runs){:target="_blank"}
+REST API: [Delete Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#delete_flow){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request.
+`flow_id` | The identifier (`id`) for the `FlowItem` that you want to delete from the server.
-**Returns**
+**Exceptions**
-Returns a list of `FlowRunItem` objects. Be aware that `flowruns.get` does *NOT* return a `PaginationItem`.
+Error | Description
+:--- | :---
+`Flow ID undefined` | Raises an exception if a valid `flow_id` is not provided.
**Version**
-Version 3.10 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-
-**Example**
-
-```py
-import tableauserverclient as TSC
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-server = TSC.Server('https://SERVERURL')
-
-with server.auth.sign_in(tableau_auth):
- all_runs, pagination_item = server.flow_runs.get()
- print("\nThere are {} flow runs on site.".format(pagination_item.total_available))
- for run in all_runs:
- print(run.id, run.status)
-```
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-#### flow_runs.get_by_id
+#### flows.download
```py
-flow_runs.get_by_id(flow_run_id)
+flows.download(flow_id, filepath=None)
```
-Returns the specified flow run item.
+Downloads the specified flow in `.tfl` or `.tflx` format.
-REST API: [Get Flow Run](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#get_flow_run){:target="_blank"}
+REST API: [Download Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#download_flow){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`flow_run_id` | The identifier (`id`) for the `FlowRunItem` to query.
+`flow_id` | The identifier (`id`) for the `FlowItem` that you want to download from the server.
+`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `filepath=None`), the file is downloaded to the current working directory.
**Exceptions**
Error | Description
:--- | :---
-`Flow ID undefined` | Raises an exception if a valid `flow_run_id` is not provided.
+`Flow ID undefined` | Raises an exception if a valid `flow_id` is not provided.
**Returns**
-Returns a `FlowRunItem`.
+The file path to the downloaded flow.
**Version**
-Version 3.10 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-flow_run = server.flow_runs.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-print(flow_run.status, flow_run.progress)
+file_path = server.flows.download('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+print("\nDownloaded the file to {0}.".format(file_path))
```
-#### flow_runs.cancel
+#### flows.get
```py
-flow_runs.cancel(flow_run_id)
+flows.get(req_options=None)
```
-Cancels the specified flow run.
+Returns all the flows for the site.
-REST API: [Cancel Flow Run](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#cancel_flow_run){:target="_blank"}
+To get the connection information for each flow, you must first populate the `FlowItem` with connection information using the [flows.populate_connections](#flowspopulate_connections) method.
+
+REST API: [Query Flows for Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flows_for_site){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`flow_run_id` | The identifier (`id`) for the `FlowRunItem` to cancel. Can be the id string or a `FlowRunItem` object.
+`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific flow, you could specify the name of the project or its id.
-**Exceptions**
+**Returns**
-Error | Description
-:--- | :---
-`Flow ID undefined` | Raises an exception if a valid `flow_run_id` is not provided.
+Returns a list of `FlowItem` objects and a `PaginationItem` object. Use these values to iterate through the results.
**Version**
-Version 3.10 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-flow_run = server.flow_runs.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-server.flow_runs.cancel(flow_run.id)
+import tableauserverclient as TSC
+tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+server = TSC.Server('https://SERVERURL')
+
+with server.auth.sign_in(tableau_auth):
+ all_flows, pagination_item = server.flows.get()
+ print("\nThere are {} flows on site: ".format(pagination_item.total_available))
+ print([flow.name for flow in all_flows])
```
-#### flow_runs.wait_for_job
+#### flows.get_by_id
```py
-flow_runs.wait_for_job(flow_run_id, *, timeout=None)
+flows.get_by_id(flow_id)
```
-Waits for the specified flow run to complete and returns the finished `FlowRunItem`. This method polls the server repeatedly using exponential backoff until the run completes, then raises an exception if it failed or was cancelled.
+Returns the specified flow item.
+
+REST API: [Query Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`flow_run_id` | The identifier (`id`) for the flow run to wait for. Can be the id string or a `FlowRunItem` object.
-`timeout` | (Optional) The maximum number of seconds to wait before raising a timeout error. If not specified, waits indefinitely.
+`flow_id` | The `flow_id` specifies the flow to query.
**Exceptions**
Error | Description
:--- | :---
-`FlowRunFailedException` | Raised if the flow run completes with a `Failed` status.
-`FlowRunCancelledException` | Raised if the flow run completes with a `Cancelled` status.
+`Flow ID undefined` | Raises an exception if a valid `flow_id` is not provided.
**Returns**
-Returns the completed `FlowRunItem` if the run succeeded.
+Returns a `FlowItem`.
**Version**
-Version 3.10 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-# Trigger a flow run and wait for it to finish
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-job = server.flows.refresh(flow)
-
-# Wait for the resulting flow run to complete
-flow_run = server.flow_runs.wait_for_job(job.id, timeout=300)
-print("Flow run completed with status: {}".format(flow_run.status))
+print(flow.name)
```
-#### flow_runs.filter
+#### flows.populate_connections
```py
-flow_runs.filter(**kwargs)
+flows.populate_connections(flow_item)
```
-Returns a list of flow runs that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
+Populates a `FlowItem` with connection information.
-**Supported fields and operators**
+This method retrieves the connection information for the specified flow. The method requires a `FlowItem` object and populates its `connections` property with a list of `ConnectionItem` objects. You must call this method before you can access the `connections` property of a `FlowItem`.
-Field | Operators
+REST API: [Query Flow Connections](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow_connections){:target="_blank"}
+
+**Parameters**
+
+Name | Description
:--- | :---
-`complete_at` | `eq`, `gt`, `gte`, `lt`, `lte`
-`flow_id` | `eq`, `in`
-`progress` | `eq`, `gt`, `gte`, `lt`, `lte`
-`started_at` | `eq`, `gt`, `gte`, `lt`, `lte`
-`user_id` | `eq`, `in`
+`flow_item` | The `flow_item` specifies the flow to populate with connection information.
-**Returns**
+**Exceptions**
-Returns a `QuerySet` of `FlowRunItem` objects.
+Error | Description
+:--- | :---
+`Flow item missing ID. Flow must be retrieved from server first.` | Raises an exception if the `flow_item` does not have an id. The `flow_item` must be retrieved from the server first.
+
+**Version**
+
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
-recent_runs = server.flow_runs.filter(flow_id=flow.id)
-for run in recent_runs:
- print(run.id, run.status)
+server.flows.populate_connections(flow)
+for connection in flow.connections:
+ print(connection.id)
```
-
-
----
-
-## 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
+#### flows.publish
```py
-GroupItem(name)
+flows.publish(flow_item, file, mode, connections=None)
```
-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.
+Publishes a flow to Tableau Server.
-Source file: models/group_item.py
+REST API: [Publish Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#publish_flow){:target="_blank"}
-**Attributes**
+**Parameters**
Name | Description
:--- | :---
-`domain_name` | The name of the Active Directory domain (`local` if local authentication is used).
-`id` | The id of the group.
-`users` | The list of users (`UserItem`).
-`name` | The name of the group. The `name` is required when you create an instance of a group.
-`minimum_site_role` | The role to grant users that are added to the group.
-`license_mode` | The mode defining when to apply licenses for group members. When the mode is `onLogin`, a license is granted for each group member when they login to a site. When the mode is `onSync`, a license is granted for group members each time the domain is synced.
-
-
-**Example**
-
-```py
- newgroup = TSC.GroupItem('My Group')
+`flow_item` | The `flow_item` specifies the flow you are publishing. The `flow_item` must have a `project_id` set.
+`file` | The file path or file object of the flow to publish. Only `.tfl` and `.tflx` files are supported.
+`mode` | Specifies whether you are publishing a new flow (`CreateNew`), or overwriting an existing one (`Overwrite`). You cannot use `Append` with flows.
+`connections` | (Optional) A list of `ConnectionItem` objects for connections in the flow that require credentials.
- # call groups.create() with new group
-```
+**Exceptions**
+Error | Description
+:--- | :---
+`Invalid mode defined.` | Raises an error if the mode specified is not valid.
+`File path does not lead to an existing file.` | Raises an error if the file path specified does not point to a valid file.
+`Only .tfl, .tflx files can be published as flows.` | Raises an error if the type of file specified is not supported.
+**Returns**
+Returns a `FlowItem` representing the published flow.
-
-
+**Version**
-### Groups methods
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-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.
+**Example**
+```py
+import tableauserverclient as TSC
+tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
+server = TSC.Server('https://SERVERURL')
-Source file: server/endpoint/groups_endpoint.py
+with server.auth.sign_in(tableau_auth):
+ project_id = 'cc867571-b4e0-4764-8083-84b9f3aa8543'
+ new_flow = TSC.FlowItem(project_id)
+ new_flow = server.flows.publish(new_flow, 'path/to/flow.tflx', TSC.Server.PublishMode.Overwrite)
+ print("Published flow ID: {0}".format(new_flow.id))
+```
-#### groups.add_user
+#### flows.refresh
```py
-groups.add_user(group_item, user_id):
+flows.refresh(flow_item)
```
-Adds a user to the specified group.
-
+Runs the specified flow and returns a `JobItem` to track the progress of the run.
-REST API [Add User to Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#add_user_to_group)
+REST API: [Run Flow Now](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#run_flow_now){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`group_item` | The `group_item` specifies the group to update.
-`user_id` | The id of the user.
-
-
-
+`flow_item` | The `FlowItem` to run.
**Returns**
-None.
+Returns a `JobItem`. Use the `jobs.wait_for_job` method to block until the job is complete.
+
+**Version**
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-# 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')
-
-
-
+flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+job = server.flows.refresh(flow)
+server.jobs.wait_for_job(job)
```
-#### groups.add_users
+#### flows.update
```py
-groups.add_users(group_item, user_id):
+flows.update(flow_item)
```
-Adds multiple users to the specified group.
-
-
-REST API [Add User to Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#add_user_to_group)
-
-**Version**
+Modifies an existing flow. Use this method to change the owner or project of a flow, or to update its tags.
-This endpoint is available with REST API version 3.21 and up. Method added in
-version v0.33
+REST API: [Update Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#update_flow){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`group_item` | The `group_item` specifies the group to update.
-`users` | An Iterable of UserItems, or user ids.
-
+`flow_item` | The `FlowItem` with updated attributes. Must have been retrieved from the server (must have an `id`).
+**Exceptions**
+Error | Description
+:--- | :---
+`Flow item missing ID. Flow must be retrieved from server first.` | Raises an exception if the `flow_item` does not have an id.
**Returns**
-list[UserItem]
+Returns the updated `FlowItem`.
+
+**Version**
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-# Adding a user to a group
-#
-# get the group item
- all_groups, pagination_item = server.groups.get()
- mygroup = all_groups[1]
-
-# Add Viewers to the group
- added_users = server.groups.add_users(
- mygroup,
- server.users.filter(site_role=TSC.UserItem.Roles.Viewer)
- )
+flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+flow.project_id = 'new-project-id'
+updated_flow = server.flows.update(flow)
```
-#### groups.create
+#### flows.update_connection
```py
-create(group_item)
+flows.update_connection(flow_item, connection_item)
```
-Creates a new local group in Tableau Server.
-
-
-REST API: [Create Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_group)
+Updates the server address, port, username, or password for the specified flow connection.
+REST API: [Update Flow Connection](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#update_flow_connection){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`group_item` | The `group_item` specifies the group to add. You first create a new instance of a `GroupItem` and pass that to this method.
-
+`flow_item` | The `FlowItem` to update.
+`connection_item` | The `ConnectionItem` with updated attributes.
+**Returns**
+Returns the updated `ConnectionItem`.
-**Returns**
-Adds new `GroupItem`.
+**Version**
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-
-# Create a new group
-
-# import tableauserverclient as TSC
-# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-# server = TSC.Server('https://SERVERURL')
-
-
-# create a new instance with the group name
- newgroup = TSC.GroupItem('My Group')
- newgroup.minimum_site_role = TSC.UserItem.Roles.ExplorerCanPublish
-
-# call the create method
- newgroup = server.groups.create(newgroup)
-
-# print the names of the groups on the server
- all_groups, pagination_item = server.groups.get()
- for group in all_groups :
- print(group.name, group.id)
+flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+server.flows.populate_connections(flow)
+connection = flow.connections[0]
+connection.server_address = 'new-server.example.com'
+updated_connection = server.flows.update_connection(flow, connection)
```
+**Workload Identity Federation (WIF):** setting `connection_item.workgroup_auth_mode` (and, for impersonation, `connection_item.auth_federation_service_account`) emits the matching attributes on the request payload via the shared `Connection.update_req` builder. Server-side handling of WIF on flow connections is governed by the flow endpoint and may differ from workbook and datasource behavior.
+
-#### groups.create_AD_group
+#### flows.populate_permissions
```py
-create_AD_group(group_item, asJob=False)
+flows.populate_permissions(flow_item)
```
-Creates an active directory group in Tableau Server.
-
-
-REST API: [Create Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_group)
-
+Populates the permissions for the specified flow.
**Parameters**
Name | Description
:--- | :---
-`group_item` | The `group_item` specifies the group to add. You first create a new instance of a `GroupItem` and pass that to this method.
-`asJob` | Boolean flag used to specify an asynchronous operation. If set to `True`, the return value will be a JobItem containing the status of the queued job. See [JobItem class](#jobitem-class).
-
-
-
+`flow_item` | The `FlowItem` to populate with permissions.
-**Returns**
-Returns the created `GroupItem` or a `JobItem` if asJob flag was set to True.
+**Version**
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-
-# Create a new group
-
-# import tableauserverclient as TSC
-# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-# server = TSC.Server('https://SERVERURL')
-
-
-# create a new instance with the group name
- newgroup = TSC.GroupItem('AD_Group_Name', 'AD_Domain_Name')
- newgroup.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
- newgroup.license_mode = TSC.GroupItem.LicenseMode.onSync
-
-# call the create method
- newgroup = server.groups.create_AD_group(newgroup)
-
-# call the create method asynchronously
- newgroup_job = server.groups.create_AD_group(newgroup, asJob=True)
-
+flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+server.flows.populate_permissions(flow)
+for permission in flow.permissions:
+ print(permission.grantee_id, permission.capabilities)
```
-#### groups.delete
+#### flows.update_permissions
```py
-groups.delete(group_id)
+flows.update_permissions(flow_item, permission_item)
```
-Deletes the group on the site.
-
-REST API: [Delete Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#remove_user_from_site)
-
+Adds or updates permissions for the specified flow.
**Parameters**
Name | Description
:--- | :---
-`group_id` | The identifier (`id`) for the group that you want to remove from the server.
-
-
-**Exceptions**
-
-Error | Description
-:--- | :---
-`Group ID undefined` | Raises an exception if a valid `group_id` is not provided.
-
-
-**Example**
-
-```py
-# Delete a group from the site
+`flow_item` | The `FlowItem` to update permissions for.
+`permission_item` | A list of `PermissionsRule` objects representing the permissions to add or update.
-# import tableauserverclient as TSC
-# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-# server = TSC.Server('https://SERVERURL')
+**Version**
- with server.auth.sign_in(tableau_auth):
- server.groups.delete('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-```
-#### groups.get
+#### flows.delete_permission
```py
-groups.get(req_options=None)
+flows.delete_permission(flow_item, capability_item)
```
-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](api-ref#groupspopulate_users) method.
-
-
-REST API: [Get Users on Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_users_on_site)
+Removes a permission from the specified flow.
**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.
-
+`flow_item` | The `FlowItem` to remove the permission from.
+`capability_item` | The `PermissionsRule` object representing the permission to remove.
-**Returns**
+**Version**
-Returns a list of `GroupItem` objects and a `PaginationItem` object. Use these values to iterate through the results.
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+
+
-**Example**
-
+#### flows.populate_dqw
```py
-# import tableauserverclient as TSC
-# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-# server = TSC.Server('https://SERVERURL')
+flows.populate_dqw(flow_item)
+```
- with server.auth.sign_in(tableau_auth):
+Populates the data quality warnings for the specified flow.
- # get the groups on the server
- all_groups, pagination_item = server.groups.get()
+**Parameters**
- # print the names of the first 100 groups
- for group in all_groups :
- print(group.name, group.id)
-```
+Name | Description
+:--- | :---
+`flow_item` | The `FlowItem` to populate with data quality warnings.
+
+**Version**
+Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+
+**Example**
+
+```py
+flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+server.flows.populate_dqw(flow)
+for dqw in flow.dqws:
+ print(dqw.message)
+```
-#### groups.populate_users
+#### flows.add_dqw
```py
-groups.populate_users(group_item, req_options=None)
+flows.add_dqw(flow_item, warning)
```
-Populates the `group_item` with the list of users.
+Adds a data quality warning to the specified flow.
+**Parameters**
-REST API: [Get Users in Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_users_in_group)
+Name | Description
+:--- | :---
+`flow_item` | The `FlowItem` to add the data quality warning to.
+`warning` | The `DQWItem` object representing the data quality warning to add.
+
+**Version**
+
+Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+
+
+
+
+#### flows.update_dqw
+
+```py
+flows.update_dqw(flow_item, warning)
+```
+
+Updates a data quality warning on the specified flow.
**Parameters**
Name | Description
:--- | :---
-`group_item` | The `group_item` specifies the group to populate with user information.
-`req_options` | (Optional) Additional request options to send to the endpoint.
+`flow_item` | The `FlowItem` to update the data quality warning on.
+`warning` | The `DQWItem` object representing the updated data quality warning.
+**Version**
+Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-**Exceptions**
+
+
-`Group item missing ID. Group must be retrieved from server first.` : Raises an error if the `group_item` is unspecified.
+#### flows.delete_dqw
+```py
+flows.delete_dqw(flow_item)
+```
-**Returns**
+Removes all data quality warnings from the specified flow.
-None. A list of `UserItem` objects are added to the group (`group_item.users`).
+**Parameters**
+
+Name | Description
+:--- | :---
+`flow_item` | The `FlowItem` to remove data quality warnings from.
+
+**Version**
+Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-**Example**
+
+
+
+#### flows.schedule_flow_run
```py
-# import tableauserverclient as TSC
+flows.schedule_flow_run(schedule_id, item)
+```
-# server = TSC.Server('https://SERVERURL')
-#
- ...
+Convenience method to add a flow to an existing schedule.
-# get the group
- all_groups, pagination_item = server.groups.get()
- mygroup = all_groups[1]
+**Parameters**
-# get the user information
- pagination_item = server.groups.populate_users(mygroup)
+Name | Description
+:--- | :---
+`schedule_id` | The identifier of the schedule to add the flow to.
+`item` | The `FlowItem` to add to the schedule.
+**Returns**
-# print the names of the users
- for user in mygroup.users :
- print(user.name)
+Returns a list of `AddResponse` objects.
+**Version**
+Version 3.3 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+**Example**
+```py
+flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+result = server.flows.schedule_flow_run('schedule-id-here', flow)
```
-#### groups.remove_user
+#### flows.filter
```py
-groups.remove_user(group_item, user_id)
+flows.filter(**kwargs)
```
-Removes a user from a group.
-
+Returns a list of flows that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
+**Supported fields and operators**
+Field | Operators
+:--- | :---
+`created_at` | `eq`, `gt`, `gte`, `lt`, `lte`
+`name` | `eq`, `in`
+`owner_name` | `eq`
+`project_id` | `eq`
+`project_name` | `eq`, `in`
+`updated` | `eq`, `gt`, `gte`, `lt`, `lte`
-REST API: [Remove User from Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#remove_user_to_group)
+**Returns**
+Returns a `QuerySet` of `FlowItem` objects.
-**Parameters**
+**Example**
-Name | Description
-:--- | :---
-`group_item` | The `group_item` specifies the group to remove the user from.
-`user_id` | The id for the user.
+```py
+matching_flows = server.flows.filter(project_name='My Project')
+for flow in matching_flows:
+ print(flow.name)
+```
+
+---
-**Exceptions**
+## Flow Runs
-Error | Description
-:--- | :---
-`Group must be populated with users first.` | Raises an error if the `group_item` is unpopulated.
+Using the TSC library, you can query flow runs on a site, get details about a specific flow run, cancel a running flow, or wait for a flow run to complete. Flow runs are created when a flow is triggered to run, either manually or on a schedule.
+The flow run resources for Tableau Server are defined in the `FlowRunItem` class. The class corresponds to the flow run resources you can access using the Tableau Server REST API.
-**Returns**
+
-None. The user is removed from the group.
+### FlowRunItem class
+The `FlowRunItem` represents the result of a flow run on Tableau Server. Instances of this class are returned by the flow run methods; you do not create them directly.
-**Example**
+**Attributes**
-```py
-# Remove a user from a group
+Name | Description
+:--- | :---
+`id` | The identifier for the flow run.
+`flow_id` | The identifier of the flow that was run.
+`status` | The current status of the flow run. Possible values include `Success`, `Failed`, and `Cancelled`.
+`started_at` | The date and time when the flow run started.
+`completed_at` | The date and time when the flow run completed. Is `None` if the run is still in progress.
+`progress` | The progress percentage of the flow run.
+`background_job_id` | The identifier of the background job associated with the flow run.
-# import tableauserverclient as TSC
-# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-# server = TSC.Server('https://SERVERURL')
+Source file: models/flow_run_item.py
- with server.auth.sign_in(tableau_auth):
+
+
- # get a group
- all_groups, pagination_item = server.groups.get()
- mygroup = all_groups[0]
+### Flow Runs methods
- # remove user '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d'
- server.groups.remove_user(mygroup, '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
+The Tableau Server Client provides several methods for interacting with flow run resources. These methods correspond to endpoints in the Tableau Server REST API.
-```
+Source file: server/endpoint/flow_runs_endpoint.py
-#### groups.remove_users
+#### flow_runs.get
```py
-groups.remove_users(group_item, user_id):
+flow_runs.get(req_options=None)
```
-Removes multiple users from the specified group.
-
-
-REST API [Remove User from Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#remove_user_to_group)
-
-**Version**
+Returns all flow runs on the site.
-This endpoint is available with REST API version 3.21 and up. Method added in
-version v0.33
+REST API: [Get Flow Runs](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#get_flow_runs){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`group_item` | The `group_item` specifies the group to update.
-`users` | An Iterable of UserItems, or user ids.
-
-
-
+`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request.
**Returns**
-None
+Returns a list of `FlowRunItem` objects. Be aware that `flowruns.get` does *NOT* return a `PaginationItem`.
+
+**Version**
+Version 3.10 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-# Removing a user from a group
-#
-# get the group item
- all_groups, pagination_item = server.groups.get()
- mygroup = all_groups[1]
+import tableauserverclient as TSC
+tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+server = TSC.Server('https://SERVERURL')
-# Remove Viewers from the group
- server.groups.remove_users(
- mygroup,
- server.users.filter(site_role=TSC.UserItem.Roles.Viewer)
- )
+with server.auth.sign_in(tableau_auth):
+ all_runs, pagination_item = server.flow_runs.get()
+ print("\nThere are {} flow runs on site.".format(pagination_item.total_available))
+ for run in all_runs:
+ print(run.id, run.status)
```
-
-#### groups.update
+#### flow_runs.get_by_id
```py
-groups.update(group_item, as_job=False)
+flow_runs.get_by_id(flow_run_id)
```
-Updates a group in Tableau Server.
-
-REST API: [Update Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#update_group)
+Returns the specified flow run item.
+REST API: [Get Flow Run](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#get_flow_run){:target="_blank"}
**Parameters**
Name | Description
:--- | :---
-`group_item` | The `group_item` specifies the group to update.
-`as_job` | (Optional) If this value is set to `True`, the update operation will be asynchronous and return a JobItem. This is only supported for Active Directory groups. By default, this value is set to `False`.
-
+`flow_run_id` | The identifier (`id`) for the `FlowRunItem` to query.
**Exceptions**
Error | Description
:--- | :---
-`Group item missing ID.` | Raises an error if the `group_item` is missing the `id` attribute.
-`Local groups cannot be updated asynchronously.` | The `as_job` attribute was set to `True` for a local group.
-
+`Flow ID undefined` | Raises an exception if a valid `flow_run_id` is not provided.
**Returns**
-The updated `GroupItem` object. If `as_job` was set to `True`, a `JobItem` will be returned instead.
+Returns a `FlowRunItem`.
+**Version**
+
+Version 3.10 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-# Fetch an existing group from server.
-groups, pagination = server.groups.get()
-group = groups[0]
-
-# Set update-able fields. Any of these can be added or removed.
-## Local group
-group.name = "new group name"
-group.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
-
-## Active Directory group
-group.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
-group.license_mode = TSC.GroupItem.LicenseMode.onLogin
-
-# Update group - synchronous
-group = server.groups.update(group)
-
-# Update group - asynchronous (only for Active Directory groups)
-job = server.groups.update(group, as_job=True)
+flow_run = server.flow_runs.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+print(flow_run.status, flow_run.progress)
```
----
-
-## GroupSets
-
-Using the TSC library, you can get information about all the group sets on a site, create or delete group sets, and add or remove groups from a group set.
-
-The group set resources for Tableau Server are defined in the `GroupSetItem` class. The class corresponds to the group set resources you can access using the Tableau Server REST API. The group set methods are based upon the endpoints for group sets in the REST API and operate on the `GroupSetItem` class.
-
-
-
-
-### GroupSetItem class
+#### flow_runs.cancel
```py
-GroupSetItem(name)
+flow_runs.cancel(flow_run_id)
```
-The `GroupSetItem` class contains the attributes for the group set resources on Tableau Server. The `GroupSetItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
+Cancels the specified flow run.
-Source file: models/groupset_item.py
+REST API: [Cancel Flow Run](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#cancel_flow_run){:target="_blank"}
-**Attributes**
+**Parameters**
Name | Description
:--- | :---
-`id` | The id of the group set.
-`name` | The name of the group set. The `name` is required when you create an instance of a group set.
-`groups` | The list of groups (`GroupItem`) that belong to this group set.
-`group_count` | The number of groups in the group set.
-
-**Example**
+`flow_run_id` | The identifier (`id`) for the `FlowRunItem` to cancel. Can be the id string or a `FlowRunItem` object.
-```py
-new_groupset = TSC.GroupSetItem('My Group Set')
+**Exceptions**
-# call groupsets.create() with new group set
-groupset = server.group_sets.create(new_groupset)
-```
+Error | Description
+:--- | :---
+`Flow ID undefined` | Raises an exception if a valid `flow_run_id` is not provided.
-
-
+**Version**
-### GroupSets methods
+Version 3.10 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
-The Tableau Server Client provides several methods for interacting with group set resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
+**Example**
-Source file: server/endpoint/groupsets_endpoint.py
+```py
+flow_run = server.flow_runs.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+server.flow_runs.cancel(flow_run.id)
+```
-#### group_sets.get
+#### flow_runs.wait_for_job
```py
-group_sets.get(req_options=None, result_level=None)
+flow_runs.wait_for_job(flow_run_id, *, timeout=None)
```
-Returns information about the group sets on the specified site.
-
-REST API: [Get Group Sets](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#get_group_sets)
-
-**Version**
-
-This endpoint is available with REST API version 3.22 and up.
+Waits for the specified flow run to complete and returns the finished `FlowRunItem`. This method polls the server repeatedly using exponential backoff until the run completes, then raises an exception if it failed or was cancelled.
**Parameters**
Name | Description
:--- | :---
-`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. Filter parameters can include `page_size` and `page_number`.
-`result_level` | (Optional) Specifies the level of detail in the response. Can be `"members"` to include member groups, or `"local"` for local group sets only.
+`flow_run_id` | The identifier (`id`) for the flow run to wait for. Can be the id string or a `FlowRunItem` object.
+`timeout` | (Optional) The maximum number of seconds to wait before raising a timeout error. If not specified, waits indefinitely.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`FlowRunFailedException` | Raised if the flow run completes with a `Failed` status.
+`FlowRunCancelledException` | Raised if the flow run completes with a `Cancelled` status.
**Returns**
-Returns a list of `GroupSetItem` objects and a `PaginationItem` object.
+Returns the completed `FlowRunItem` if the run succeeded.
+
+**Version**
+
+Version 3.10 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-all_groupsets, pagination_item = server.group_sets.get()
-for groupset in all_groupsets:
- print(groupset.id, groupset.name)
+# Trigger a flow run and wait for it to finish
+flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+job = server.flows.refresh(flow)
+
+# Wait for the resulting flow run to complete
+flow_run = server.flow_runs.wait_for_job(job.id, timeout=300)
+print("Flow run completed with status: {}".format(flow_run.status))
```
-#### group_sets.get_by_id
+#### flow_runs.filter
```py
-group_sets.get_by_id(groupset_id)
+flow_runs.filter(**kwargs)
```
-Returns information about the specified group set.
-
-REST API: [Get Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#get_group_set)
-
-**Version**
-
-This endpoint is available with REST API version 3.22 and up.
+Returns a list of flow runs that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
-**Parameters**
+**Supported fields and operators**
-Name | Description
+Field | Operators
:--- | :---
-`groupset_id` | The id of the group set.
+`complete_at` | `eq`, `gt`, `gte`, `lt`, `lte`
+`flow_id` | `eq`, `in`
+`progress` | `eq`, `gt`, `gte`, `lt`, `lte`
+`started_at` | `eq`, `gt`, `gte`, `lt`, `lte`
+`user_id` | `eq`, `in`
**Returns**
-Returns a `GroupSetItem` object.
+Returns a `QuerySet` of `FlowRunItem` objects.
**Example**
```py
-groupset = server.group_sets.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
-print(groupset.name)
+flow = server.flows.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+recent_runs = server.flow_runs.filter(flow_id=flow.id)
+for run in recent_runs:
+ print(run.id, run.status)
```
+
+
+---
+
+## Groups
+
+Using the TSC library, you can get information about all the groups on a site, you can add or remove groups, or add or remove users in a group.
+
+The group resources for Tableau Server are defined in the `GroupItem` class. The class corresponds to the group resources you can access using the Tableau Server REST API. The group methods are based upon the endpoints for groups in the REST API and operate on the `GroupItem` class.
+
-#### group_sets.create
+### GroupItem class
```py
-group_sets.create(groupset_item)
+GroupItem(name)
```
-Creates a new group set on the specified site.
-
-REST API: [Create Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#create_group_set)
-
-**Version**
+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.
-This endpoint is available with REST API version 3.22 and up.
+Source file: models/group_item.py
-**Parameters**
+**Attributes**
Name | Description
:--- | :---
-`groupset_item` | The `GroupSetItem` specifies the group set to add. You first create a new instance of a `GroupSetItem` and pass that to this method.
-
-**Returns**
+`domain_name` | The name of the Active Directory domain (`local` if local authentication is used).
+`id` | The id of the group.
+`users` | The list of users (`UserItem`).
+`name` | The name of the group. The `name` is required when you create an instance of a group.
+`minimum_site_role` | The role to grant users that are added to the group.
+`license_mode` | The mode defining when to apply licenses for group members. When the mode is `onLogin`, a license is granted for each group member when they login to a site. When the mode is `onSync`, a license is granted for group members each time the domain is synced.
-Returns the newly created `GroupSetItem` object.
**Example**
```py
-new_groupset = TSC.GroupSetItem('My Group Set')
-created_groupset = server.group_sets.create(new_groupset)
-print(created_groupset.id)
-```
-
-
-
-
-#### group_sets.update
+ newgroup = TSC.GroupItem('My Group')
-```py
-group_sets.update(groupset_item)
+ # call groups.create() with new group
```
-Modifies an existing group set. You can use this method to rename a group set.
-
-REST API: [Update Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#update_group_set)
-**Version**
-This endpoint is available with REST API version 3.22 and up.
-**Parameters**
+
+
-Name | Description
-:--- | :---
-`groupset_item` | The `GroupSetItem` to update. The group set item must have a valid `id`.
+### Groups methods
-**Returns**
+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.
-Returns the updated `GroupSetItem` object.
-**Example**
-```py
-groupset.name = 'Renamed Group Set'
-updated_groupset = server.group_sets.update(groupset)
-```
+Source file: server/endpoint/groups_endpoint.py
-#### group_sets.delete
+#### groups.add_user
```py
-group_sets.delete(groupset)
+groups.add_user(group_item, user_id):
```
-Deletes the specified group set from the site.
-
-REST API: [Delete Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#delete_group_set)
+Adds a user to the specified group.
-**Version**
-This endpoint is available with REST API version 3.22 and up.
+REST API [Add User to Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#add_user_to_group)
**Parameters**
Name | Description
:--- | :---
-`groupset` | The `GroupSetItem` or group set id (`str`) to delete.
+`group_item` | The `group_item` specifies the group to update.
+`user_id` | The id of the user.
+
+
+
**Returns**
None.
+
**Example**
```py
-server.group_sets.delete(groupset.id)
+# 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')
+
+
+
```
-#### group_sets.add_group
+#### groups.add_users
```py
-group_sets.add_group(groupset_item, group)
+groups.add_users(group_item, user_id):
```
-Adds a group to the specified group set.
+Adds multiple users to the specified group.
-REST API: [Add Group to Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#add_group_to_group_set)
+
+REST API [Add User to Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#add_user_to_group)
**Version**
-This endpoint is available with REST API version 3.22 and up.
+This endpoint is available with REST API version 3.21 and up. Method added in
+version v0.33
**Parameters**
Name | Description
:--- | :---
-`groupset_item` | The `GroupSetItem` specifying the group set to update.
-`group` | The `GroupItem` or group id (`str`) to add to the group set.
+`group_item` | The `group_item` specifies the group to update.
+`users` | An Iterable of UserItems, or user ids.
+
+
+
**Returns**
-None.
+list[UserItem]
+
**Example**
```py
-all_groups, _ = server.groups.get()
-mygroup = all_groups[0]
+# Adding a user to a group
+#
+# get the group item
+ all_groups, pagination_item = server.groups.get()
+ mygroup = all_groups[1]
-server.group_sets.add_group(groupset, mygroup)
+# Add Viewers to the group
+ added_users = server.groups.add_users(
+ mygroup,
+ server.users.filter(site_role=TSC.UserItem.Roles.Viewer)
+ )
```
-#### group_sets.remove_group
+#### groups.create
```py
-group_sets.remove_group(groupset_item, group)
+create(group_item)
```
-Removes a group from the specified group set.
+Creates a new local group in Tableau Server.
-REST API: [Remove Group from Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#remove_group_from_group_set)
-**Version**
+REST API: [Create Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_group)
-This endpoint is available with REST API version 3.22 and up.
**Parameters**
Name | Description
:--- | :---
-`groupset_item` | The `GroupSetItem` specifying the group set to update.
-`group` | The `GroupItem` or group id (`str`) to remove from the group set.
+`group_item` | The `group_item` specifies the group to add. You first create a new instance of a `GroupItem` and pass that to this method.
+
+
+
**Returns**
+Adds new `GroupItem`.
-None.
**Example**
```py
-server.group_sets.remove_group(groupset, mygroup)
+
+# Create a new group
+
+# import tableauserverclient as TSC
+# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+# server = TSC.Server('https://SERVERURL')
+
+
+# create a new instance with the group name
+ newgroup = TSC.GroupItem('My Group')
+ newgroup.minimum_site_role = TSC.UserItem.Roles.ExplorerCanPublish
+
+# call the create method
+ newgroup = server.groups.create(newgroup)
+
+# print the names of the groups on the server
+ all_groups, pagination_item = server.groups.get()
+ for group in all_groups :
+ print(group.name, group.id)
```
-#### group_sets.filter
+#### groups.create_AD_group
```py
-group_sets.filter(**kwargs)
+create_AD_group(group_item, asJob=False)
```
-Returns a list of group sets that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
+Creates an active directory group in Tableau Server.
-**Version**
-This endpoint is available with REST API version 3.22 and up.
+REST API: [Create Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_group)
-**Supported fields and operators**
-Field | Operators
+**Parameters**
+
+Name | Description
:--- | :---
-`domain_name` | `eq`, `in`
-`domain_nickname` | `eq`, `in`
-`is_external_user_enabled` | `eq`
-`is_local` | `eq`
-`luid` | `eq`, `in`
-`minimum_site_role` | `eq`, `in`
-`name` | `eq`, `cieq`, `in`, `like`
-`user_count` | `eq`, `gt`, `gte`, `lt`, `lte`
+`group_item` | The `group_item` specifies the group to add. You first create a new instance of a `GroupItem` and pass that to this method.
+`asJob` | Boolean flag used to specify an asynchronous operation. If set to `True`, the return value will be a JobItem containing the status of the queued job. See [JobItem class](#jobitem-class).
+
+
+
**Returns**
+Returns the created `GroupItem` or a `JobItem` if asJob flag was set to True.
-Returns a `QuerySet` of `GroupSetItem` objects.
**Example**
```py
-local_groupsets = server.group_sets.filter(is_local=True)
-for groupset in local_groupsets:
- print(groupset.name)
-```
-
-
+# Create a new group
----
+# import tableauserverclient as TSC
+# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+# server = TSC.Server('https://SERVERURL')
-## Jobs
-Using the TSC library, you can get information about an asynchronous process (or *job*) on the server. These jobs can be created when Tableau runs certain tasks that could be long running, such as importing or synchronizing users from Active Directory, or running an extract refresh. For example, the REST API methods to create or update groups, to run an extract refresh task, or to publish workbooks can take an `asJob` parameter (`asJob-true`) that creates a background process (the *job*) to complete the call. Information about the asynchronous job is returned from the method.
+# create a new instance with the group name
+ newgroup = TSC.GroupItem('AD_Group_Name', 'AD_Domain_Name')
+ newgroup.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
+ newgroup.license_mode = TSC.GroupItem.LicenseMode.onSync
-If you have the identifier of the job, you can use the TSC library to find out the status of the asynchronous job.
+# call the create method
+ newgroup = server.groups.create_AD_group(newgroup)
+
+# call the create method asynchronously
+ newgroup_job = server.groups.create_AD_group(newgroup, asJob=True)
-The job properties are defined in the `JobItem` class. The class corresponds to the properties for jobs you can access using the Tableau Server REST API. The job methods are based upon the endpoints for jobs in the REST API and operate on the `JobItem` class.
+```
+
+
-### JobItem class
+#### groups.delete
```py
-JobItem(id, type, created_at, started_at=None, completed_at=None, finish_code=0)
-
+groups.delete(group_id)
```
-The `JobItem` class contains information about the specified job running on Tableau Server. The `JobItem` class defines the information you can query from Tableau Server. The class members correspond to the attributes of a server response payload.
+Deletes the group on the site.
-Source file: models/job_item.py
+REST API: [Delete Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#remove_user_from_site)
-**Attributes**
-Name | Description
+**Parameters**
+
+Name | Description
:--- | :---
-`id` | The `id` of the job.
-`type` | The type of task. The types correspond to the job type categories listed for the [Query Job](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_job) REST API.
-`created_at` | The time the job was created.
-`started_at` | The time the job started.
-`completed_at` | The time the job finished.
-`finish_code` | The return code from job.
-`progress` | The progress of the job.
-`notes` | The notes of the job.
-`mode` | The mode of the job.
+`group_id` | The identifier (`id`) for the group that you want to remove from the server.
-### Jobs methods
+**Exceptions**
-The Jobs methods are based upon the endpoints for jobs in the REST API and operate on the `JobItem` class.
+Error | Description
+:--- | :---
+`Group ID undefined` | Raises an exception if a valid `group_id` is not provided.
-Source files: server/endpoint/jobs_endpoint.py
+**Example**
+
+```py
+# Delete a group from the site
+
+# import tableauserverclient as TSC
+# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+# server = TSC.Server('https://SERVERURL')
+ with server.auth.sign_in(tableau_auth):
+ server.groups.delete('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
+
+```
-#### jobs.get
+#### groups.get
```py
-jobs.get(job_id=None, req_options=None)
+groups.get(req_options=None)
```
-Retrieve jobs for the site. Endpoint is paginated and will return a list of jobs and pagination information. If a job_id is provided, the method will return information about that specific job. Specifying a job_id is deprecated and will be removed in a future version.
+Returns information about the groups on the site.
-REST API: [Get Background Jobs on Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#get_background_jobs_on_site){:target="_blank"}
+To get information about the users in a group, you must first populate the `GroupItem` with user information using the [groups.populate_users](api-ref#groupspopulate_users) method.
+
+
+REST API: [Get Users on Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_users_on_site)
**Parameters**
Name | Description
:--- | :---
-`job_id` | (Optional) The `job_id` specifies the job to query. When provided, returns the status of that specific job.
-`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request.
+`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific group, you could specify the name of the group or the group id.
-**Returns**
-Returns a list of `BackgroundJobItem` objects and a `PaginationItem` object.
+**Returns**
-**Version**
+Returns a list of `GroupItem` objects and a `PaginationItem` object. Use these values to iterate through the results.
-Version 2.6 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
+
```py
-import tableauserverclient as TSC
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-server = TSC.Server('https://SERVERURL')
+# import tableauserverclient as TSC
+# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+# server = TSC.Server('https://SERVERURL')
-with server.auth.sign_in(tableau_auth):
- all_jobs, pagination_item = server.jobs.get()
- print("\nThere are {} jobs on site: ".format(pagination_item.total_available))
- print([job.id for job in all_jobs])
+ 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)
```
+
-#### jobs.get_by_id
-
+#### groups.populate_users
```py
-jobs.get_by_id(job_id)
+groups.populate_users(group_item, req_options=None)
```
-Gets information about the specified job.
+Populates the `group_item` with the list of users.
-REST API: [Query Job](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_job)
+REST API: [Get Users in Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_users_in_group)
**Parameters**
Name | Description
:--- | :---
-`job_id` | The `job_id` specifies the id of the job that is returned from an asynchronous task, such as extract refresh, or an import or update to groups using Active Directory
-
+`group_item` | The `group_item` specifies the group to populate with user information.
+`req_options` | (Optional) Additional request options to send to the endpoint.
**Exceptions**
-Error | Description
-:--- | :---
-`404018 Resource Not Found` | Raises an error if the `job_id` is not found.
+`Group item missing ID. Group must be retrieved from server first.` : Raises an error if the `group_item` is unspecified.
**Returns**
-Returns the `JobItem` requested.
+None. A list of `UserItem` objects are added to the group (`group_item.users`).
**Example**
```py
-# Query a Job
-
# import tableauserverclient as TSC
-# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
-# server = TSC.Server('https://SERVERURL')
-
- with server.auth.sign_in(tableau_auth):
- # get the id of the job from response to extract refresh task,
- # or another asynchronous REST API call.
- # in this case, "576b616d-341a-4539-b32c-1ed0eb9db548"
+# server = TSC.Server('https://SERVERURL')
+#
+ ...
+# get the group
+ all_groups, pagination_item = server.groups.get()
+ mygroup = all_groups[1]
- myJobId = '576b616d-341a-4539-b32c-1ed0eb9db548'
- jobinfo = server.jobs.get_by_id(myJobId)
+# get the user information
+ pagination_item = server.groups.populate_users(mygroup)
- print(jobinfo)
- #
+# print the names of the users
+ for user in mygroup.users :
+ print(user.name)
```
-
-#### jobs.cancel
+#### groups.remove_user
```py
-jobs.cancel(job_id)
+groups.remove_user(group_item, user_id)
```
-Cancels the currently running job. Can be used to cancel currently running jobs like extract refreshes.
+Removes a user from a group.
-**Parameters**
-Name | Description
-:----|:----
-`job_id` | The `job_id` specifies the id of the job that we want to cancel. It is the id of the job that is retunred from an asynchronous taks, such as extract refresh, run a flow, or import or update to groups using Active Directory.
-**Exceptions**
-Error | Description
-:----|:----
-404 Resource Not Found | Raises an error if the `job_id` is not found.
+REST API: [Remove User from Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#remove_user_to_group)
+
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`group_item` | The `group_item` specifies the group to remove the user from.
+`user_id` | The id for the user.
+
+
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`Group must be populated with users first.` | Raises an error if the `group_item` is unpopulated.
+
+
+**Returns**
+
+None. The user is removed from the group.
-**Returns** Returns the details of the canceled job including the URL of the site where the job was created.
**Example**
+
```py
-# Query a Job
+# Remove a user from a group
# import tableauserverclient as TSC
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
@@ -4998,2827 +5091,4141 @@ Error | Description
with server.auth.sign_in(tableau_auth):
- # get the id of the job from response from the query job method.
- # in this example, "576b781d-331c-4539-b61d-1ed0eb9db548"
- cancelJobId = '576b781d-331c-4539-b61d-1ed0eb9db548'
- jobs.cancel (cancelJobId)
+ # get a group
+ all_groups, pagination_item = server.groups.get()
+ mygroup = all_groups[0]
+
+ # remove user '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d'
+ server.groups.remove_user(mygroup, '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
```
-#### jobs.wait_for_job
+
+
+#### groups.remove_users
```py
-jobs.wait_for_job(job_id, *, timeout=None)
+groups.remove_users(group_item, user_id):
```
-Waits until a given job succesfully finishes.
-Repeatedly polls the server using `jobs.get_by_id` until the job completed.
-It uses an exponentially increasing sleep time between polls to guarantee a snappy response time for fast-running jobs while not putting overly large load on the server for long-running jobs.
+Removes multiple users from the specified group.
-In case the job fails or is cancelled, `wait_for_job` will raise an exception.
+
+REST API [Remove User from Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#remove_user_to_group)
+
+**Version**
+
+This endpoint is available with REST API version 3.21 and up. Method added in
+version v0.33
**Parameters**
Name | Description
:--- | :---
-`job_id` | The `job_id` specifies the id of the job that we want to wait for
-`timeout` | Optional timeout interval in seconds. `wait_for_job` will raise a `TimeoutError` if the job is not finished after waiting for `timeout` seconds.
+`group_item` | The `group_item` specifies the group to update.
+`users` | An Iterable of UserItems, or user ids.
+
+
**Returns**
-Returns the final `JobItem`.
+None
-Usually, you can just discard the return value without checking the job status. In case the job wasn't succesful, `wait_for_job` would have already raised an exception. For advanced scenarios, the returned `JobItem` might still be interesting to access e.g. start and end time or `notes`.
**Example**
-See the `update_datasource_data.py` or `refresh.py` sample in the Samples directory.
+```py
+# Removing a user from a group
+#
+# get the group item
+ all_groups, pagination_item = server.groups.get()
+ mygroup = all_groups[1]
+
+# Remove Viewers from the group
+ server.groups.remove_users(
+ mygroup,
+ server.users.filter(site_role=TSC.UserItem.Roles.Viewer)
+ )
+```
-#### jobs.filter
+
+#### groups.update
```py
-jobs.filter(**kwargs)
+groups.update(group_item, as_job=False)
```
-Returns a list of background jobs that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
+Updates a group in Tableau Server.
-**Supported fields and operators**
+REST API: [Update Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#update_group)
-Field | Operators
+
+**Parameters**
+
+Name | Description
:--- | :---
-`args` | `has`
-`completed_at` | `eq`, `gt`, `gte`, `lt`, `lte`
-`created_at` | `eq`, `gt`, `gte`, `lt`, `lte`
-`job_type` | `eq`, `in`
-`notes` | `has`
-`priority` | `eq`, `gt`, `gte`, `lt`, `lte`
-`progress` | `eq`, `gt`, `gte`, `lt`, `lte`
-`started_at` | `eq`, `gt`, `gte`, `lt`, `lte`
-`status` | `eq`
-`subtitle` | `eq`, `has`
-`title` | `eq`, `has`
+`group_item` | The `group_item` specifies the group to update.
+`as_job` | (Optional) If this value is set to `True`, the update operation will be asynchronous and return a JobItem. This is only supported for Active Directory groups. By default, this value is set to `False`.
+
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`Group item missing ID.` | Raises an error if the `group_item` is missing the `id` attribute.
+`Local groups cannot be updated asynchronously.` | The `as_job` attribute was set to `True` for a local group.
+
**Returns**
-Returns a `QuerySet` of `BackgroundJobItem` objects.
+The updated `GroupItem` object. If `as_job` was set to `True`, a `JobItem` will be returned instead.
+
**Example**
```py
-failed_jobs = server.jobs.filter(status='Failed')
-for job in failed_jobs:
- print(job.id, job.type)
-```
+# Fetch an existing group from server.
+groups, pagination = server.groups.get()
+group = groups[0]
-
-
+# Set update-able fields. Any of these can be added or removed.
+## Local group
+group.name = "new group name"
+group.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
----
+## Active Directory group
+group.minimum_site_role = TSC.UserItem.Roles.SiteAdministratorExplorer
+group.license_mode = TSC.GroupItem.LicenseMode.onLogin
-## Metadata
+# Update group - synchronous
+group = server.groups.update(group)
-Using the `metadata` endpoint, one can use GraphQL to query metadata on, e.g., workbooks, datasources, the fields contained within them, and the relationships between them.
+# Update group - asynchronous (only for Active Directory groups)
+job = server.groups.update(group, as_job=True)
+```
-### Metadata methods
+
+
+---
-The Metadata methods call the [Metadata API](https://help.tableau.com/current/api/metadata_api/en-us/index.html) which is a GraphQL interface allowing to query metadata about objects on the server (workbooks, datasources, ...) and the relationships between them.
+## GroupSets
+Using the TSC library, you can get information about all the group sets on a site, create or delete group sets, and add or remove groups from a group set.
-Source files: server/endpoint/metadata_endpoint.py
+The group set resources for Tableau Server are defined in the `GroupSetItem` class. The class corresponds to the group set resources you can access using the Tableau Server REST API. The group set methods are based upon the endpoints for group sets in the REST API and operate on the `GroupSetItem` class.
-
-#### metadata.query
-
+### GroupSetItem class
```py
-metadata.query(query, variables=None, abort_on_error=False)
+GroupSetItem(name)
```
-Executes a metadata query and returns the result.
+The `GroupSetItem` class contains the attributes for the group set resources on Tableau Server. The `GroupSetItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
+Source file: models/groupset_item.py
-**Parameters**
+**Attributes**
Name | Description
:--- | :---
-`query` | The GraphQL query
-`variables` | Variables for the GraphQL query
-`abort_on_error` | Whether to throw an exception on error
+`id` | The id of the group set.
+`name` | The name of the group set. The `name` is required when you create an instance of a group set.
+`groups` | The list of groups (`GroupItem`) that belong to this group set.
+`group_count` | The number of groups in the group set.
+**Example**
-**Returns**
+```py
+new_groupset = TSC.GroupSetItem('My Group Set')
-The method returns the query results as a stucture of `list`s and `dict`s as returned by the `json` package.
+# call groupsets.create() with new group set
+groupset = server.group_sets.create(new_groupset)
+```
+
+
-**Example**
+### GroupSets methods
-See the `metadata_query.py` sample in the Samples directory.
+The Tableau Server Client provides several methods for interacting with group set resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
+
+Source file: server/endpoint/groupsets_endpoint.py
-#### metadata.paginated_query
-
+#### group_sets.get
```py
-metadata.paginated_query(query, variables=None, abort_on_error=False)
+group_sets.get(req_options=None, result_level=None)
```
-Executes a metadata query, and returns a dictionary containing a list of the results. In order to properly paginate through all the results, the query must contain a field `pageInfo` with the subfields `hasNextPage` and `endCursor`, as well as the nodes to be returned. The query must accept the variables `first` (the number of items to return) and `afterToken` (the cursor after which to return items). The method will repeatedly call the metadata endpoint until all results have been retrieved, and return a dictionary containing a list of all results.
+Returns information about the group sets on the specified site.
+REST API: [Get Group Sets](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#get_group_sets)
+
+**Version**
+This endpoint is available with REST API version 3.22 and up.
**Parameters**
Name | Description
:--- | :---
-`query` | The GraphQL query
-`variables` | Variables for the GraphQL query
-`abort_on_error` | Whether to throw an exception on error
-
+`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. Filter parameters can include `page_size` and `page_number`.
+`result_level` | (Optional) Specifies the level of detail in the response. Can be `"members"` to include member groups, or `"local"` for local group sets only.
**Returns**
-The method returns the query results in a dictionary containing a list of pages as a stucture of `list`s and `dict`s as returned by the `json` package.
-
+Returns a list of `GroupSetItem` objects and a `PaginationItem` object.
**Example**
-See the `metadata_paginated_query.py` sample in the Samples directory.
+```py
+all_groupsets, pagination_item = server.group_sets.get()
+for groupset in all_groupsets:
+ print(groupset.id, groupset.name)
+```
----
+#### group_sets.get_by_id
-## Metrics
+```py
+group_sets.get_by_id(groupset_id)
+```
-Using the TSC library, you can get information about all metrics on a site, update, or delete metrics.
+Returns information about the specified group set.
-
+REST API: [Get Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#get_group_set)
-### MetricItem class
+**Version**
-```py
-MetricItem(name: Optional[str]=None)
-```
-The metrics resources for Tableau are defined in the `MetricItem` class. The class corresponds to the metric resource you can access using the Tableau Server REST API.
+This endpoint is available with REST API version 3.22 and up.
+
+**Parameters**
-**Attributes**
Name | Description
:--- | :---
-`name` | Name of the metric
-`id` | The REST API id for the metric
-`description` | The description of the metric
-`webpage_url` | The URL for the metric
-`created_at` | The datetime object for when the metric was created
-`updated_at` | The datetime object for when the metric was updated
-`suspended` | Boolean for if the metric is in a suspended state
-`project_id` | REST API id for the project containing the metric
-`project_name` | The name of the project containing the metric
-`owner_id` | REST API id for the user who owns the metric
-`view_id` | REST API id for the view from which the metric was created
+`groupset_id` | The id of the group set.
+
+**Returns**
+Returns a `GroupSetItem` object.
+**Example**
-Source file: models/metric_item.py
+```py
+groupset = server.group_sets.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
+print(groupset.name)
+```
-### Metric methods
+#### group_sets.create
-The metric methods are based upon the endpoints for metrics in the REST API and operate on the `MetricItem` class. The metrics endpoint also supports the django style filtering.
-See [Filter and Sort](filter-sort) for more information.
+```py
+group_sets.create(groupset_item)
+```
-Source files: server/endpoint/metrics_endpoint.py
+Creates a new group set on the specified site.
+
+REST API: [Create Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#create_group_set)
+
+**Version**
+
+This endpoint is available with REST API version 3.22 and up.
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`groupset_item` | The `GroupSetItem` specifies the group set to add. You first create a new instance of a `GroupSetItem` and pass that to this method.
+
+**Returns**
+
+Returns the newly created `GroupSetItem` object.
+
+**Example**
+
+```py
+new_groupset = TSC.GroupSetItem('My Group Set')
+created_groupset = server.group_sets.create(new_groupset)
+print(created_groupset.id)
+```
-#### metrics.delete
+#### group_sets.update
```py
-metrics.delete(metric_id)
-
+group_sets.update(groupset_item)
```
-Deletes a metric item from a site.
-
+Modifies an existing group set. You can use this method to rename a group set.
-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](#tableauauth-class).
+REST API: [Update Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#update_group_set)
-REST API: [Delete Metric](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_metric)
+**Version**
+This endpoint is available with REST API version 3.22 and up.
**Parameters**
Name | Description
:--- | :---
-`metric_id` | The id of the metric to delete
-
-
+`groupset_item` | The `GroupSetItem` to update. The group set item must have a valid `id`.
**Returns**
-None
-
-
+Returns the updated `GroupSetItem` object.
- **Example**
+**Example**
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc
-
-server.metrics.delete("6561daa3-20e8-407f-ba09-709b178c0b4a")
-
+groupset.name = 'Renamed Group Set'
+updated_groupset = server.group_sets.update(groupset)
```
-#### metrics.get
+#### group_sets.delete
```py
-metrics.get()
-
+group_sets.delete(groupset)
```
-Return a list of metrics items for a site.
-
+Deletes the specified group set from the site.
-To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class).
+REST API: [Delete Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#delete_group_set)
-REST API: [List Metrics for Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#list_metrics_for_site)
+**Version**
+This endpoint is available with REST API version 3.22 and up.
**Parameters**
-None.
+Name | Description
+:--- | :---
+`groupset` | The `GroupSetItem` or group set id (`str`) to delete.
**Returns**
-Returns a Tuple containing a list of all `MetricItem` objects and a `PaginationItem`. Use these values to iterate through the results.
-
-
+None.
- **Example**
+**Example**
```py
-import tableauserverclient as TSC
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
-server = TSC.Server('https://SERVER')
-
-with server.auth.sign_in(tableau_auth):
- # get all metrics on site
- all_metric_items, pagination_item = server.metrics.get()
- print([metric.name for metric in all_metric_items])
-
+server.group_sets.delete(groupset.id)
```
-#### metrics.get_by_id
+#### group_sets.add_group
```py
-metrics.get_by_id(metric_id)
-
+group_sets.add_group(groupset_item, group)
```
-Return a specific metric item from the site.
-
+Adds a group to the specified group set.
-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](#tableauauth-class).
+REST API: [Add Group to Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#add_group_to_group_set)
-REST API: [Get Metric](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_metric)
+**Version**
+This endpoint is available with REST API version 3.22 and up.
**Parameters**
-
Name | Description
:--- | :---
-`metric_id` | The id of the desired metric
-
-
+`groupset_item` | The `GroupSetItem` specifying the group set to update.
+`group` | The `GroupItem` or group id (`str`) to add to the group set.
**Returns**
-Returns a `MetricItem` object corresponding to the ID requested.
-
-
+None.
- **Example**
+**Example**
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc
-
-server.metrics.get_by_id("6561daa3-20e8-407f-ba09-709b178c0b4a")
+all_groups, _ = server.groups.get()
+mygroup = all_groups[0]
+server.group_sets.add_group(groupset, mygroup)
```
-#### metrics.update
+#### group_sets.remove_group
```py
-metrics.update(item)
-
+group_sets.remove_group(groupset_item, group)
```
-Updates a metric item on the Tableau Server.
-
+Removes a group from the specified group set.
-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](#tableauauth-class).
+REST API: [Remove Group from Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#remove_group_from_group_set)
-REST API: [Update Metric](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_metric)
+**Version**
+This endpoint is available with REST API version 3.22 and up.
**Parameters**
-
Name | Description
:--- | :---
-`metric_item` | The altered `MetricItem` to be updated on the Tableau Server
-
+`groupset_item` | The `GroupSetItem` specifying the group set to update.
+`group` | The `GroupItem` or group id (`str`) to remove from the group set.
**Returns**
-Returns a `MetricItem` object reflecting the changes applied to Tableau Server.
-
-
+None.
- **Example**
+**Example**
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc
-
-metric = server.metrics.get_by_id("6561daa3-20e8-407f-ba09-709b178c0b4a")
-metric.owner_id = "1bbbc2b9-847d-443c-9a1f-dbcf112b8814"
-server.metrics.update(metric)
+server.group_sets.remove_group(groupset, mygroup)
```
+#### group_sets.filter
+```py
+group_sets.filter(**kwargs)
+```
+Returns a list of group sets that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
----
+**Version**
-## Projects
+This endpoint is available with REST API version 3.22 and up.
-Using the TSC library, you can get information about all the projects on a site, or you can create, update projects, or remove projects.
+**Supported fields and operators**
-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.
+Field | Operators
+:--- | :---
+`domain_name` | `eq`, `in`
+`domain_nickname` | `eq`, `in`
+`is_external_user_enabled` | `eq`
+`is_local` | `eq`
+`luid` | `eq`, `in`
+`minimum_site_role` | `eq`, `in`
+`name` | `eq`, `cieq`, `in`, `like`
+`user_count` | `eq`, `gt`, `gte`, `lt`, `lte`
+**Returns**
+Returns a `QuerySet` of `GroupSetItem` objects.
+**Example**
+```py
+local_groupsets = server.group_sets.filter(is_local=True)
+for groupset in local_groupsets:
+ print(groupset.name)
+```
+
-### ProjectItem class
+---
-```py
+## Jobs
-ProjectItem(name, description=None, content_permissions=None, parent_id=None)
+Using the TSC library, you can get information about an asynchronous process (or *job*) on the server. These jobs can be created when Tableau runs certain tasks that could be long running, such as importing or synchronizing users from Active Directory, or running an extract refresh. For example, the REST API methods to create or update groups, to run an extract refresh task, or to publish workbooks can take an `asJob` parameter (`asJob-true`) that creates a background process (the *job*) to complete the call. Information about the asynchronous job is returned from the method.
-```
-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.
+If you have the identifier of the job, you can use the TSC library to find out the status of the asynchronous job.
-**Attributes**
+The job properties are defined in the `JobItem` class. The class corresponds to the properties for jobs you can access using the Tableau Server REST API. The job methods are based upon the endpoints for jobs in the REST API and operate on the `JobItem` class.
-Name | Description
-:--- | :---
-`content_permissions` | Sets or shows the permissions for the content in the project. The options are either `LockedToProject`, `ManagedByOwner` or `LockedToProjectWithoutNested`.
-`name` | Name of the project.
-`description` | The description of the project.
-`id` | The project id.
-`parent_id` | The id of the parent project. Use this option to create project hierarchies. For information about managing projects, project hierarchies, and permissions, see [Use Projects to Manage Content Access](https://help.tableau.com/current/server/en-us/projects.htm).
+### JobItem class
+```py
+JobItem(id, type, created_at, started_at=None, completed_at=None, finish_code=0)
-Source file: models/project_item.py
+```
+The `JobItem` class contains information about the specified job running on Tableau Server. The `JobItem` class defines the information you can query from Tableau Server. The class members correspond to the attributes of a server response payload.
-#### ProjectItem.ContentPermissions
+Source file: models/job_item.py
-The `ProjectItem` class has a sub-class that defines the permissions for the project (`ProjectItem.ContentPermissions`). The options are `LockedToProject`, `ManagedByOwner` and `LockedToProjectWithoutNested`. For information on these content permissions, see [Lock Content Permissions to the Project](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_project).
+**Attributes**
-Name | Description
+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**
+`id` | The `id` of the job.
+`type` | The type of task. The types correspond to the job type categories listed for the [Query Job](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_job) REST API.
+`created_at` | The time the job was created.
+`started_at` | The time the job started.
+`completed_at` | The time the job finished.
+`finish_code` | The return code from job.
+`progress` | The progress of the job.
+`notes` | The notes of the job.
+`mode` | The mode of the job.
-```py
+### Jobs methods
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc
+The Jobs methods are based upon the endpoints for jobs in the REST API and operate on the `JobItem` class.
-locked_true = TSC.ProjectItem.ContentPermissions.LockedToProject
-print(locked_true)
-# prints 'LockedToProject'
-by_owner = TSC.ProjectItem.ContentPermissions.ManagedByOwner
-print(by_owner)
-# prints 'ManagedByOwner'
+Source files: server/endpoint/jobs_endpoint.py
+
+
-# 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')
+#### jobs.get
+```py
+jobs.get(job_id=None, req_options=None)
```
-
-
+Retrieve jobs for the site. Endpoint is paginated and will return a list of jobs and pagination information. If a job_id is provided, the method will return information about that specific job. Specifying a job_id is deprecated and will be removed in a future version.
-### Project methods
-The project methods are based upon the endpoints for projects in the REST API and operate on the `ProjectItem` class.
+REST API: [Get Background Jobs on Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#get_background_jobs_on_site){:target="_blank"}
+**Parameters**
-Source files: server/endpoint/projects_endpoint.py
+Name | Description
+:--- | :---
+`job_id` | (Optional) The `job_id` specifies the job to query. When provided, returns the status of that specific job.
+`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request.
-
-
+**Returns**
+Returns a list of `BackgroundJobItem` objects and a `PaginationItem` object.
-#### projects.create
+**Version**
+
+Version 2.6 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+
+**Example**
```py
-projects.create(project_item)
+import tableauserverclient as TSC
+tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+server = TSC.Server('https://SERVERURL')
+
+with server.auth.sign_in(tableau_auth):
+ all_jobs, pagination_item = server.jobs.get()
+ print("\nThere are {} jobs on site: ".format(pagination_item.total_available))
+ print([job.id for job in all_jobs])
```
+
+
-Creates a project on the specified site.
+#### jobs.get_by_id
-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](#tableauauth-class).
+```py
+jobs.get_by_id(job_id)
+```
+
+Gets information about the specified job.
+
+REST API: [Query Job](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_job)
-REST API: [Create Project](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_project)
**Parameters**
Name | Description
:--- | :---
-`project_item` | Specifies the properties for the project. The `project_item` is the request package. To create the request package, create a new instance of `ProjectItem`.
+`job_id` | The `job_id` specifies the id of the job that is returned from an asynchronous task, such as extract refresh, or an import or update to groups using Active Directory
+
+
+
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`404018 Resource Not Found` | Raises an error if the `job_id` is not found.
**Returns**
-Returns the new project item.
+Returns the `JobItem` requested.
**Example**
```py
-import tableauserverclient as TSC
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
-server = TSC.Server('https://SERVER')
+# Query a Job
-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)
+# import tableauserverclient as TSC
+# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+# server = TSC.Server('https://SERVERURL')
-```
+ with server.auth.sign_in(tableau_auth):
-
-
+ # get the id of the job from response to extract refresh task,
+ # or another asynchronous REST API call.
+ # in this case, "576b616d-341a-4539-b32c-1ed0eb9db548"
+
+
+ myJobId = '576b616d-341a-4539-b32c-1ed0eb9db548'
+ jobinfo = server.jobs.get_by_id(myJobId)
+
+ print(jobinfo)
+
+ #
-#### projects.get
-```py
-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](#tableauauth-class).
+#### jobs.cancel
-REST API: [Query Projects](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_projects)
+```py
+jobs.cancel(job_id)
+```
+Cancels the currently running job. Can be used to cancel currently running jobs like extract refreshes.
**Parameters**
-None.
+Name | Description
+:----|:----
+`job_id` | The `job_id` specifies the id of the job that we want to cancel. It is the id of the job that is retunred from an asynchronous taks, such as extract refresh, run a flow, or import or update to groups using Active Directory.
-**Returns**
+**Exceptions**
-Returns a list of all `ProjectItem` objects and a `PaginationItem`. Use these values to iterate through the results.
+Error | Description
+:----|:----
+404 Resource Not Found | Raises an error if the `job_id` is not found.
+**Returns** Returns the details of the canceled job including the URL of the site where the job was created.
+**Example**
+```py
+# Query a Job
- **Example**
+# import tableauserverclient as TSC
+# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+# server = TSC.Server('https://SERVERURL')
-```py
-import tableauserverclient as TSC
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
-server = TSC.Server('https://SERVER')
+ with server.auth.sign_in(tableau_auth):
-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])
+ # 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
-#### projects.update
```py
-projects.update(project_item)
+jobs.wait_for_job(job_id, *, timeout=None)
```
-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](#tableauauth-class).
+Waits until a given job succesfully finishes.
+Repeatedly polls the server using `jobs.get_by_id` until the job completed.
+It uses an exponentially increasing sleep time between polls to guarantee a snappy response time for fast-running jobs while not putting overly large load on the server for long-running jobs.
-REST API: [Update Project](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_project)
+In case the job fails or is cancelled, `wait_for_job` will raise an exception.
**Parameters**
-Name | Description
+Name | Description
:--- | :---
-`project_item` | The project item object must include the project ID. The values in the project item override the current project settings.
+`job_id` | The `job_id` specifies the id of the job that we want to wait for
+`timeout` | Optional timeout interval in seconds. `wait_for_job` will raise a `TimeoutError` if the job is not finished after waiting for `timeout` seconds.
-**Exceptions**
+**Returns**
-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 the final `JobItem`.
+Usually, you can just discard the return value without checking the job status. In case the job wasn't succesful, `wait_for_job` would have already raised an exception. For advanced scenarios, the returned `JobItem` might still be interesting to access e.g. start and end time or `notes`.
-**Returns**
+**Example**
-Returns the updated project information.
+See the `update_datasource_data.py` or `refresh.py` sample in the Samples directory.
-See [ProjectItem class](#projectitem-class)
+
+
-**Example**
+#### jobs.filter
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc
+jobs.filter(**kwargs)
+```
- ...
- # get list of projects
- all_project_items, pagination_item = server.projects.get()
+Returns a list of background jobs that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
+**Supported fields and operators**
- # update project item #7 with new name, etc.
- my_project = all_projects[7]
- my_project.name ='New name'
- my_project.description = 'New description'
+Field | Operators
+:--- | :---
+`args` | `has`
+`completed_at` | `eq`, `gt`, `gte`, `lt`, `lte`
+`created_at` | `eq`, `gt`, `gte`, `lt`, `lte`
+`job_type` | `eq`, `in`
+`notes` | `has`
+`priority` | `eq`, `gt`, `gte`, `lt`, `lte`
+`progress` | `eq`, `gt`, `gte`, `lt`, `lte`
+`started_at` | `eq`, `gt`, `gte`, `lt`, `lte`
+`status` | `eq`
+`subtitle` | `eq`, `has`
+`title` | `eq`, `has`
- # call method to update project
- updated_project = server.projects.update(my_project)
+**Returns**
+
+Returns a `QuerySet` of `BackgroundJobItem` objects.
+
+**Example**
+```py
+failed_jobs = server.jobs.filter(status='Failed')
+for job in failed_jobs:
+ print(job.id, job.type)
```
+
+---
-#### projects.delete
+## Metadata
-```py
-projects.delete(project_id)
-```
+Using the `metadata` endpoint, one can use GraphQL to query metadata on, e.g., workbooks, datasources, the fields contained within them, and the relationships between them.
-Deletes a project by ID.
+### Metadata methods
-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](#tableauauth-class).
+The Metadata methods call the [Metadata API](https://help.tableau.com/current/api/metadata_api/en-us/index.html) which is a GraphQL interface allowing to query metadata about objects on the server (workbooks, datasources, ...) and the relationships between them.
-REST API: [Delete Project](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_project)
+Source files: server/endpoint/metadata_endpoint.py
+
+
+
+
+
+#### metadata.query
+
+
+```py
+metadata.query(query, variables=None, abort_on_error=False)
+```
+
+Executes a metadata query and returns the result.
**Parameters**
-Name | Description
+Name | Description
:--- | :---
-`project_id` | The ID of the project to delete.
+`query` | The GraphQL query
+`variables` | Variables for the GraphQL query
+`abort_on_error` | Whether to throw an exception on error
-**Exceptions**
+**Returns**
-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.
+The method returns the query results as a stucture of `list`s and `dict`s as returned by the `json` package.
**Example**
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
+See the `metadata_query.py` sample in the Samples directory.
- server.projects.delete('1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e')
+
+
-```
+#### metadata.paginated_query
-#### projects.populate_permissions
```py
-projects.populate_permissions(item)
+metadata.paginated_query(query, variables=None, abort_on_error=False)
```
-Queries the project permissions, parses and stores the returned the permissions.
-
-REST API: [Query Project Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_project_permissions){:target="_blank"}
+Executes a metadata query, and returns a dictionary containing a list of the results. In order to properly paginate through all the results, the query must contain a field `pageInfo` with the subfields `hasNextPage` and `endCursor`, as well as the nodes to be returned. The query must accept the variables `first` (the number of items to return) and `afterToken` (the cursor after which to return items). The method will repeatedly call the metadata endpoint until all results have been retrieved, and return a dictionary containing a list of all results.
-**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
+**Parameters**
-**Example**
-
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
+Name | Description
+:--- | :---
+`query` | The GraphQL query
+`variables` | Variables for the GraphQL query
+`abort_on_error` | Whether to throw an exception on error
- all_project_items, pagination_item = server.projects.get()
- project_item = all_project_items[0]
- server.projects.populate_permissions(project_item)
-```
+**Returns**
-#### projects.update_permissions
-```py
-projects.update_permissions(item, rules)
-```
+The method returns the query results in a dictionary containing a list of pages as a stucture of `list`s and `dict`s as returned by the `json` package.
-Add project permissions for a user or group.
-REST API: [Add Project Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#add_project_permissions){:target="_blank"}
+**Example**
-**Parameters**
+See the `metadata_paginated_query.py` sample in the Samples directory.
-Name | Description
-:--- | :---
-`item` | A project object.
-`rules` | A list of PermissionsRule objects.
+
+
-**Example**
-
-```py
-# 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
- }
+## Metrics
- project_rules = TSC.PermissionsRule(
- grantee=project_item,
- capabilities=project_capabilities
- )
-
- server.projects.update_permissions(project_item, [project_rules])
-```
+Using the TSC library, you can get information about all metrics on a site, update, or delete metrics.
+
+
+### MetricItem class
-#### projects.delete_permission
```py
-projects.delete_permission(item, rules)
+MetricItem(name: Optional[str]=None)
```
+The metrics resources for Tableau are defined in the `MetricItem` class. The class corresponds to the metric resource you can access using the Tableau Server REST API.
-Delete project permissions.
+**Attributes**
+Name | Description
+:--- | :---
+`name` | Name of the metric
+`id` | The REST API id for the metric
+`description` | The description of the metric
+`webpage_url` | The URL for the metric
+`created_at` | The datetime object for when the metric was created
+`updated_at` | The datetime object for when the metric was updated
+`suspended` | Boolean for if the metric is in a suspended state
+`project_id` | REST API id for the project containing the metric
+`project_name` | The name of the project containing the metric
+`owner_id` | REST API id for the user who owns the metric
+`view_id` | REST API id for the view from which the metric was created
-REST API: [Delete Project Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_project_permission){:target="_blank"}
-**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
-`rules` | A list of PermissionsRule objects or a single PermissionsRule object.
+Source file: models/metric_item.py
-**Example**
-
-```py
-# 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
- }
+### Metric methods
- project_rules = TSC.PermissionsRule(
- grantee=project_item,
- capabilities=project_capabilities
- )
-
- server.projects.delete_permission(project_item)
-```
+The metric methods are based upon the endpoints for metrics in the REST API and operate on the `MetricItem` class. The metrics endpoint also supports the django style filtering.
+See [Filter and Sort](filter-sort) for more information.
+
+Source files: server/endpoint/metrics_endpoint.py
+
+
+
+#### metrics.delete
-#### projects.populate_workbook_default_permissions
```py
-projects.populate_workbook_default_permissions(item)
+metrics.delete(metric_id)
+
```
-Queries the default workbook permissions, parses and stores the returned the permissions.
+Deletes a metric item from a site.
+
+
+To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class).
+
+REST API: [Delete Metric](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_metric)
-REST API: [Query Default Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions){:target="_blank"}
**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
+Name | Description
+:--- | :---
+`metric_id` | The id of the metric to delete
-**Example**
-
-```py
-# 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
-```py
-projects.populate_datasource_default_permissions(item)
-```
+**Returns**
-Queries the default datasource permissions, parses and stores the returned the permissions.
+None
-REST API: [Query Default Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions){:target="_blank"}
-**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
+ **Example**
-**Example**
-
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
+# 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)
-```
+server.metrics.delete("6561daa3-20e8-407f-ba09-709b178c0b4a")
+
+```
+
+
+
+#### metrics.get
-#### projects.populate_flow_default_permissions
```py
-projects.populate_flow_default_permissions(item)
+metrics.get()
+
```
-Queries the default flow permissions, parses and stores the returned the permissions.
+Return a list of metrics items for a site.
-REST API: [Query Default Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions){:target="_blank"}
+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](#tableauauth-class).
-**Parameters**
+REST API: [List Metrics for Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#list_metrics_for_site)
-Name | Description
-:--- | :---
-`item` | A project object.
-**Example**
-
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
+**Parameters**
- all_project_items, pagination_item = server.projects.get()
- project_item = all_project_items[0]
- server.projects.populate_flow_default_permissions(project_item)
-```
+None.
-#### projects.update_workbook_default_permissions
-```py
-projects.update_workbook_default_permissions(item, rules)
-```
+**Returns**
-Add or update default workbook permissions.
+Returns a Tuple containing a list of all `MetricItem` objects and a `PaginationItem`. Use these values to iterate through the results.
-REST API: [Add Default Workbook Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#add_default_permissions){:target="_blank"}
-**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
-`rules` | A list of PermissionsRule objects.
+ **Example**
-**Example**
-
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
+import tableauserverclient as TSC
+tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
+server = TSC.Server('https://SERVER')
- all_project_items, pagination_item = server.projects.get()
- project_item = all_project_items[0]
-
- capabilities = {
- TSC.Permission.Capability.ViewComments: TSC.Permission.Mode.Allow
- }
+with server.auth.sign_in(tableau_auth):
+ # get all metrics on site
+ all_metric_items, pagination_item = server.metrics.get()
+ print([metric.name for metric in all_metric_items])
- rules = TSC.PermissionsRule(
- grantee=project_item,
- capabilities=capabilities
- )
-
- server.projects.update_workbook_default_permissions(project_item, [rules])
-```
+```
+
+
+
+
+#### metrics.get_by_id
-#### projects.update_datasource_default_permissions
```py
-projects.update_datasource_default_permissions(item, rules)
+metrics.get_by_id(metric_id)
+
```
-Add or update default datasource permissions.
+Return a specific metric item from the site.
+
+
+To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class).
+
+REST API: [Get Metric](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_metric)
-REST API: [Add Default Datasource Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#add_default_permissions){:target="_blank"}
**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
-`rules` | A list of PermissionsRule objects.
-
-**Example**
-
-```py
-# 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
- }
+Name | Description
+:--- | :---
+`metric_id` | The id of the desired metric
- rules = TSC.PermissionsRule(
- grantee=project_item,
- capabilities=capabilities
- )
-
- server.projects.update_datasource_default_permissions(project_item, [rules])
-```
-#### projects.update_flow_default_permissions
-```py
-projects.update_flow_default_permissions(item, rules)
-```
+**Returns**
-Add or update default flow permissions.
+Returns a `MetricItem` object corresponding to the ID requested.
-REST API: [Add Default Flow Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#add_default_permissions){:target="_blank"}
-**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
-`rules` | A list of PermissionsRule objects.
+ **Example**
-**Example**
-
```py
-# 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
- }
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, etc
- rule = TSC.PermissionsRule(
- grantee=project_item,
- capabilities=capabilities
- )
-
- server.projects.update_flow_default_permissions(project_item, [rule])
-```
+server.metrics.get_by_id("6561daa3-20e8-407f-ba09-709b178c0b4a")
-#### projects.delete_workbook_default_permissions
-```py
-projects.delete_workbook_default_permissions(item, rule)
```
-Delete default workbook permissions.
-
-REST API: [Delete Default Workbook Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission){:target="_blank"}
-
-**Parameters**
+
+
-Name | Description
-:--- | :---
-`item` | A project object.
-`rule` | A PermissionsRule object.
+#### metrics.update
-**Example**
-
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
+metrics.update(item)
- 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)
-```
+Updates a metric item on the Tableau Server.
-#### projects.delete_datasource_default_permissions
-```py
-projects.delete_datasource_default_permissions(item, rule)
-```
-Delete default datasource 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](#tableauauth-class).
-REST API: [Delete Default Datasource Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission){:target="_blank"}
+REST API: [Update Metric](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_metric)
-**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
-`rule` | A PermissionsRule object.
+**Parameters**
-**Example**
-
-```py
-# 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
- }
+Name | Description
+:--- | :---
+`metric_item` | The altered `MetricItem` to be updated on the Tableau Server
- rule = TSC.PermissionsRule(
- grantee=project_item,
- capabilities=capabilities
- )
-
- server.projects.delete_datasource_default_permissions(project_item, rule)
-```
-#### projects.delete_flow_default_permissions
-```py
-projects.delete_flow_default_permissions(item, rule)
-```
+**Returns**
-Delete default flow permissions.
+Returns a `MetricItem` object reflecting the changes applied to Tableau Server.
-REST API: [Delete Default Flow Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission){:target="_blank"}
-**Parameters**
-Name | Description
-:--- | :---
-`item` | A project object.
-`rule` | A PermissionsRule object.
+ **Example**
-**Example**
-
```py
-# 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
- }
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, etc
- rule = TSC.PermissionsRule(
- grantee=project_item,
- capabilities=capabilities
- )
-
- server.projects.delete_flow_default_permissions(project_item, rule)
-```
+metric = server.metrics.get_by_id("6561daa3-20e8-407f-ba09-709b178c0b4a")
+metric.owner_id = "1bbbc2b9-847d-443c-9a1f-dbcf112b8814"
+server.metrics.update(metric)
+```
----
-
-## 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
+---
+## Projects
-You can use the `ImageRequestOptions` and `PDFRequestOptions` to set options for views returned as images and PDF files.
+Using the TSC library, you can get information about all the projects on a site, or you can create, update projects, or remove projects.
-**Note**: View filters set via `vf()` on `CSVRequestOptions`, `ImageRequestOptions`, or `PDFRequestOptions` apply exact-match only. Operators like greater-than, less-than, contains, or value ranges are not supported by the underlying REST endpoint. See the Tableau REST API [filtering documentation](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm) for the server-side detail. If you need range filtering for exports, expose the range bounds as workbook parameters and use `.parameter()` to set them.
+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.
-For more information about filtering and sorting, see [Filter and Sort](filter-sort).
-
+
-### RequestOptions class
+### ProjectItem class
```py
-RequestOptions(pagenumber=1, pagesize=100)
-
-```
+ProjectItem(name, description=None, content_permissions=None, parent_id=None)
+```
+The project resources for Tableau are defined in the `ProjectItem` class. The class corresponds to the project resources you can access using the Tableau Server REST API.
**Attributes**
Name | Description
:--- | :---
-`pagenumber` | The page number of the returned results. The default value is 1.
-`pagesize` | The number of items to return with each page (the default value is 100).
-`sort()` | Returns a iterable set of `Sort` objects.
-`filter()` | Returns an iterable set of `Filter` objects.
-
-
-
+`content_permissions` | Sets or shows the permissions for the content in the project. The options are either `LockedToProject`, `ManagedByOwner` or `LockedToProjectWithoutNested`.
+`name` | Name of the project.
+`description` | The description of the project.
+`id` | The project id.
+`parent_id` | The id of the parent project. Use this option to create project hierarchies. For information about managing projects, project hierarchies, and permissions, see [Use Projects to Manage Content Access](https://help.tableau.com/current/server/en-us/projects.htm).
-#### RequestOptions.Field class
+Source file: models/project_item.py
-The `RequestOptions.Field` class corresponds to the fields used in filter expressions in the Tableau REST API. For more information, see [Filtering and Sorting](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm) in the Tableau REST API.
-**Attributes**
+#### ProjectItem.ContentPermissions
-**Attributes**
+The `ProjectItem` class has a sub-class that defines the permissions for the project (`ProjectItem.ContentPermissions`). The options are `LockedToProject`, `ManagedByOwner` and `LockedToProjectWithoutNested`. For information on these content permissions, see [Lock Content Permissions to the Project](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_project).
-Field | Description
+Name | 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`
+`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**
-
-
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, etc
-#### RequestOptions.Operator class
+locked_true = TSC.ProjectItem.ContentPermissions.LockedToProject
+print(locked_true)
+# prints 'LockedToProject'
-Specifies the operators you can use to filter requests.
+by_owner = TSC.ProjectItem.ContentPermissions.ManagedByOwner
+print(by_owner)
+# prints 'ManagedByOwner'
-**Attributes**
+# 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')
-Operator | Description
-:--- | :---
-`Equals` | Sets the operator to equals (same as `eq` in the REST API). `TSC.RequestOptions.Operator.Equals`
-`GreaterThan` | Sets the operator to greater than (same as `gt` in the REST API). `TSC.RequestOptions.Operator.GreaterThan`
-`GreaterThanOrEqual` | Sets the operator to greater than or equal (same as `gte` in the REST API). `TSC.RequestOptions.Operator.GreaterThanOrEqual`
+```
+
+
+
+
+### 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
+
+```py
+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](#tableauauth-class).
+
+
+REST API: [Create Project](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_project)
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`project_item` | Specifies the properties for the project. The `project_item` is the request package. To create the request package, create a new instance of `ProjectItem`.
+
+
+**Returns**
+Returns the new project item.
+
+
+
+**Example**
+
+```py
+import tableauserverclient as TSC
+tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
+server = TSC.Server('https://SERVER')
+
+with server.auth.sign_in(tableau_auth):
+ # create project item
+ new_project = TSC.ProjectItem(name='Example Project', content_permissions='LockedToProject', description='Project created for testing')
+ # create the project
+ new_project = server.projects.create(new_project)
+
+```
+
+
+
+
+
+#### projects.get
+
+```py
+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](#tableauauth-class).
+
+REST API: [Query Projects](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_projects)
+
+
+**Parameters**
+
+None.
+
+**Returns**
+
+Returns a list of all `ProjectItem` objects and a `PaginationItem`. Use these values to iterate through the results.
+
+
+
+ **Example**
+
+```py
+import tableauserverclient as TSC
+tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
+server = TSC.Server('https://SERVER')
+
+with server.auth.sign_in(tableau_auth):
+ # get all projects on site
+ all_project_items, pagination_item = server.projects.get()
+ print([proj.name for proj in all_project_items])
+
+```
+
+
+
+
+
+#### projects.update
+
+```py
+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](#tableauauth-class).
+
+REST API: [Update Project](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_project)
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`project_item` | The project item object must include the project ID. The values in the project item override the current project settings.
+
+
+**Exceptions**
+
+Error | Description
+ :--- | : ---
+`Project item missing ID.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI.
+
+
+**Returns**
+
+Returns the updated project information.
+
+See [ProjectItem class](#projectitem-class)
+
+**Example**
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, etc
+
+ ...
+ # get list of projects
+ all_project_items, pagination_item = server.projects.get()
+
+
+ # update project item #7 with new name, etc.
+ my_project = all_projects[7]
+ my_project.name ='New name'
+ my_project.description = 'New description'
+
+ # call method to update project
+ updated_project = server.projects.update(my_project)
+
+```
+
+
+
+
+#### projects.delete
+
+```py
+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](#tableauauth-class).
+
+
+REST API: [Delete Project](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#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**
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, etc.
+
+ server.projects.delete('1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e')
+
+```
+
+
+#### projects.populate_permissions
+```py
+projects.populate_permissions(item)
+```
+
+Queries the project permissions, parses and stores the returned the permissions.
+
+REST API: [Query Project Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_project_permissions){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+
+
+**Example**
+
+```py
+# 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
+```py
+projects.update_permissions(item, rules)
+```
+
+Add project permissions for a user or group.
+
+REST API: [Add Project Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#add_project_permissions){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+`rules` | A list of PermissionsRule objects.
+
+**Example**
+
+```py
+# 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
+```py
+projects.delete_permission(item, rules)
+```
+
+Delete project permissions.
+
+REST API: [Delete Project Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_project_permission){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+`rules` | A list of PermissionsRule objects or a single PermissionsRule object.
+
+**Example**
+
+```py
+# 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
+```py
+projects.populate_workbook_default_permissions(item)
+```
+
+Queries the default workbook permissions, parses and stores the returned the permissions.
+
+REST API: [Query Default Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+
+**Example**
+
+```py
+# 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
+```py
+projects.populate_datasource_default_permissions(item)
+```
+
+Queries the default datasource permissions, parses and stores the returned the permissions.
+
+REST API: [Query Default Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+
+**Example**
+
+```py
+# 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
+```py
+projects.populate_flow_default_permissions(item)
+```
+
+Queries the default flow permissions, parses and stores the returned the permissions.
+
+REST API: [Query Default Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions){:target="_blank"}
+
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+
+**Example**
+
+```py
+# 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
+```py
+projects.update_workbook_default_permissions(item, rules)
+```
+
+Add or update default workbook permissions.
+
+REST API: [Add Default Workbook Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#add_default_permissions){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+`rules` | A list of PermissionsRule objects.
+
+**Example**
+
+```py
+# 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
+```py
+projects.update_datasource_default_permissions(item, rules)
+```
+
+Add or update default datasource permissions.
+
+REST API: [Add Default Datasource Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#add_default_permissions){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+`rules` | A list of PermissionsRule objects.
+
+**Example**
+
+```py
+# 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
+```py
+projects.update_flow_default_permissions(item, rules)
+```
+
+Add or update default flow permissions.
+
+REST API: [Add Default Flow Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#add_default_permissions){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+`rules` | A list of PermissionsRule objects.
+
+**Example**
+
+```py
+# 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
+```py
+projects.delete_workbook_default_permissions(item, rule)
+```
+
+Delete default workbook permissions.
+
+REST API: [Delete Default Workbook Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+`rule` | A PermissionsRule object.
+
+**Example**
+
+```py
+# 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
+```py
+projects.delete_datasource_default_permissions(item, rule)
+```
+
+Delete default datasource permissions.
+
+REST API: [Delete Default Datasource Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+`rule` | A PermissionsRule object.
+
+**Example**
+
+```py
+# 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
+```py
+projects.delete_flow_default_permissions(item, rule)
+```
+
+Delete default flow permissions.
+
+REST API: [Delete Default Flow Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission){:target="_blank"}
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`item` | A project object.
+`rule` | A PermissionsRule object.
+
+**Example**
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, etc.
+
+ all_project_items, pagination_item = server.projects.get()
+ project_item = all_project_items[0]
+
+ capabilities = {
+ TSC.Permission.Capability.Read: TSC.Permission.Mode.Allow
+ }
+
+ rule = TSC.PermissionsRule(
+ grantee=project_item,
+ capabilities=capabilities
+ )
+
+ server.projects.delete_flow_default_permissions(project_item, rule)
+```
+
+
+
+
+---
+
+## Requests
+
+The TSC library provides a `RequestOptions` class that you can use to filter results returned from the server.
+
+You can use the `Sort` and `RequestOptions` classes to filter and sort the following endpoints:
+
+- Users
+- Datasources
+- Groups
+- Workbooks
+- Views
+
+
+You can use the `ImageRequestOptions` and `PDFRequestOptions` to set options for views returned as images and PDF files.
+
+**Note**: View filters set via `vf()` on `CSVRequestOptions`, `ImageRequestOptions`, or `PDFRequestOptions` apply exact-match only. Operators like greater-than, less-than, contains, or value ranges are not supported by the underlying REST endpoint. See the Tableau REST API [filtering documentation](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm) for the server-side detail. If you need range filtering for exports, expose the range bounds as workbook parameters and use `.parameter()` to set them.
+
+For more information about filtering and sorting, see [Filter and Sort](filter-sort).
+
+
+
+
+
+
+### RequestOptions class
+
+```py
+RequestOptions(pagenumber=1, pagesize=100)
+
+```
+
+
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`pagenumber` | The page number of the returned results. The default value is 1.
+`pagesize` | The number of items to return with each page (the default value is 100).
+`sort()` | Returns a iterable set of `Sort` objects.
+`filter()` | Returns an iterable set of `Filter` objects.
+
+
+
+
+
+
+#### RequestOptions.Field class
+
+The `RequestOptions.Field` class corresponds to the fields used in filter expressions in the Tableau REST API. For more information, see [Filtering and Sorting](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm) in the Tableau REST API.
+
+**Attributes**
+
+**Attributes**
+
+Field | Description
+:--- | :---
+`CreatedAt` | Same as 'createdAt' in the REST API. TSC. `RequestOptions.Field.CreatedAt`
+`LastLogin` | Same as 'lastLogin' in the REST API. `RequestOptions.Field.LastLogin`
+`Name` | Same as 'name' in the REST API. `RequestOptions.Field.Name`
+`OwnerName` | Same as 'ownerName' in the REST API. `RequestOptions.Field.OwnerName`
+`SiteRole` | Same as 'siteRole' in the REST API. `RequestOptions.Field.SiteRole`
+`Tags` | Same as 'tags' in the REST API. `RequestOptions.Field.Tags`
+`UpdatedAt` | Same as 'updatedAt' in the REST API. `RequestOptions.Field.UpdatedAt`
+
+
+
+
+
+
+
+#### RequestOptions.Operator class
+
+Specifies the operators you can use to filter requests.
+
+
+**Attributes**
+
+Operator | Description
+:--- | :---
+`Equals` | Sets the operator to equals (same as `eq` in the REST API). `TSC.RequestOptions.Operator.Equals`
+`GreaterThan` | Sets the operator to greater than (same as `gt` in the REST API). `TSC.RequestOptions.Operator.GreaterThan`
+`GreaterThanOrEqual` | Sets the operator to greater than or equal (same as `gte` in the REST API). `TSC.RequestOptions.Operator.GreaterThanOrEqual`
`LessThan` | Sets the operator to less than (same as `lt` in the REST API). `TSC.RequestOptions.Operator.LessThan`
`LessThanOrEqual` | Sets the operator to less than or equal (same as `lte` in the REST API). `TSC.RequestOptions.Operator.LessThanOrEqual`
`In` | Sets the operator to in (same as `in` in the REST API). `TSC.RequestOptions.Operator.In`
-
-
+
+
+
+
+
+#### RequestOptions.Direction class
+
+Specifies the direction to sort the returned fields.
+
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`Asc` | Sets the sort direction to ascending (`TSC.RequestOptions.Direction.Asc`)
+`Desc` | Sets the sort direction to descending (`TSC.RequestOptions.Direction.Desc`).
+
+
+
+
+### CSVRequestOptions class
+
+```py
+CSVRequestOptions(maxage=-1)
+```
+Use this class to specify view filters to be applied when the CSV data is generated. Optionally, you can specify the maximum age of the CSV data cached on the server by providing a `maxage` value. See `views.populate_csv`.
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`maxage` | Optional. The maximum number of minutes the CSV data will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
+
+**Example**
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set view filters
+csv_req_option = TSC.CSVRequestOptions(maxage=5)
+csv_req_option.vf('Region', 'South')
+csv_req_option.vf('Category', 'Furniture')
+
+# retrieve the csv data for the view
+server.views.populate_csv(view_item, csv_req_option)
+```
+
+If you set a parameter in the workbook, you can also pass the parameter value as part of the `CSVRequestOptions` object. For example, if you have a parameter named `Region` in the workbook, you can set the parameter value to `South` as follows:
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set view filters
+csv_req_option = TSC.CSVRequestOptions(maxage=5)
+csv_req_option.parameter('Region', 'South')
+
+# retrieve the csv data for the view
+server.views.populate_csv(view_item, csv_req_option)
+```
+
+### ExcelRequestOptions class
+
+```py
+ExcelRequestOptions(maxage=-1)
+```
+Use this class to specify view filters to be applied when data is generated in an Excel file format. Optionally, you can specify the maximum age of the Excel data cached on the server by providing a `maxage` value. See `views.populate_csv`.
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`maxage` | Optional. The maximum number of minutes the Excel data will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
+
+**Example**
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set view filters
+excel_req_option = TSC.ExcelRequestOptions(maxage=5)
+excel_req_option.vf('Region', 'South')
+excel_req_option.vf('Category', 'Furniture')
+
+# retrieve the excel data for the view
+server.views.populate_excel(view_item, excel_req_option)
+```
+
+If you set a parameter in the workbook, you can also pass the parameter value as part of the `ExcelRequestOptions` object. For example, if you have a parameter named `Region` in the workbook, you can set the parameter value to `South` as follows:
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set view filters
+excel_req_option = TSC.ExcelRequestOptions(maxage=5)
+excel_req_option.parameter('Region', 'South')
+
+# retrieve the excel data for the view
+server.views.populate_excel(view_item, excel_req_option)
+```
+
+### ImageRequestOptions class
+
+```py
+ImageRequestOptions(imageresolution=None, maxage=-1)
+```
+Use this class to specify the resolution of the view and, optionally, the maximum age of the image cached on the server. You can also use this class to specify view filters to be applied when the image is generated. See `views.populate_image`.
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`imageresolution` | The resolution of the view returned as an image. If unspecified, the `views.populate_image` method returns an image with standard resolution (the width of the returned image is 784 pixels). If you set this parameter value to high (`Resolution.High`), the width of the returned image is 1568 pixels. For both resolutions, the height varies to preserve the aspect ratio of the view.
+`maxage` | Optional. The maximum number of minutes the image will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
+
+**View Filters**
+
+You can use the `vf('filter_name', 'filter_value')` method to add view filters. When the image is generated, the specified filters will be applied to the view.
+
+**Example**
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set the image request option
+image_req_option = TSC.ImageRequestOptions(imageresolution=TSC.ImageRequestOptions.Resolution.High, maxage=1)
+
+# (optional) set a view filter
+image_req_option.vf('Category', 'Furniture')
+
+# retrieve the image for the view
+server.views.populate_image(view_item, image_req_option)
+
+```
+
+
+If you set a parameter in the workbook, you can also pass the parameter value as part of the `ImageRequestOptions` object. For example, if you have a parameter named `Region` in the workbook, you can set the parameter value to `South` as follows:
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set view filters
+image_req_option = TSC.ImageRequestOptions(maxage=5)
+image_req_option.parameter('Region', 'South')
+
+# retrieve the image data for the view
+server.views.populate_image(view_item, image_req_option)
+```
+
+### PDFRequestOptions class
+
+```py
+PDFRequestOptions(page_type=None, orientation=None, maxage=-1)
+```
+Use this class to specify the format of the PDF that is returned for the view. Optionally, you can specify the maximum age of the rendered PDF that is cached on the server by providing a `maxage` value. See `views.populate_pdf`.
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`page_type` | The type of page returned in PDF format for the view. The page_type is set using the `PageType` class:
`PageType.A3`
`PageType.A4`
`PageType.A5`
`PageType.B5`
`PageType.Executive`
`PageType.Folio`
`PageType.Ledger`
`PageType.Legal`
`PageType.Letter`
`PageType.Note`
`PageType.Quarto`
`PageType.Tabloid`
`PageType.Unspecified`
+`orientation` | The orientation of the page. The options are portrait and landscape. The options are set using the `Orientation` class:
`Orientation.Portrait`
`Orientation.Landscape`
+`maxage` | Optional. The maximum number of minutes the rendered PDF will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
+`viz_height` | Optional. The height of the output PDF in pixels. If specified, viz_width must also be specified.
+`viz_width` | Optional. The width of the output PDF in pixels. If specified, viz_height must also be specified.
+
+**View Filters**
+You can use the `vf('filter_name', 'filter_value')` method to add view filters. When the PDF is generated, the specified filters will be applied to the view.
+
+**Example**
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set the PDF request options
+pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4,
+ orientation=TSC.PDFRequestOptions.Orientation.Landscape,
+ maxage=1)
+
+# (optional) set a view filter
+pdf_req_option.vf('Region', 'West')
+
+# retrieve the PDF for a view
+server.views.populate_pdf(view_item, pdf_req_option)
+
+```
+
+
+You can also specify height and width for the visualization to be rendered in the PDF. If you specify the height and width, you must specify both values. The height and width are set in pixels.
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set the PDF request options
+pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4,
+ orientation=TSC.PDFRequestOptions.Orientation.Landscape,
+ maxage=1,
+ viz_height=800,
+ viz_width=1200)
+
+server.views.populate_pdf(view_item, pdf_req_option)
+
+```
+
+If you set a parameter in the workbook, you can also pass the parameter value as part of the `PDFRequestOptions` object. For example, if you have a parameter named `Region` in the workbook, you can set the parameter value to `South` as follows:
+
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, get a specific view, etc.
+
+# set view filters
+pdf_req_option = TSC.PDFRequestOptions(maxage=5)
+pdf_req_option.parameter('Region', 'South')
+
+# retrieve the pdf data for the view
+server.views.populate_pdf(view_item, pdf_req_option)
+```
+
+
+
+
+---
+
+## Schedules
+
+Using the TSC library, you can schedule extract refresh or subscription tasks on Tableau Server. You can also get and update information about the scheduled tasks, or delete scheduled tasks.
+
+If you have the identifier of the job, you can use the TSC library to find out the status of the asynchronous job.
+
+The schedule properties are defined in the `ScheduleItem` class. The class corresponds to the properties for schedules you can access in Tableau Server or by using the Tableau Server REST API. The Schedule methods are based upon the endpoints for jobs in the REST API and operate on the `JobItem` class.
+
+
+### ScheduleItem class
+
+```py
+ScheduleItem(name, priority, schedule_type, execution_order, interval_item)
+
+```
+
+The `ScheduleItem` class contains information about the specified schedule running on Tableau Server. The `ScheduleItem` class defines the information you can query and set. The class members correspond to the attributes of a server response payload.
+
+Source file: models/schedule_item.py
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`name` | The `name` of the schedule.
+`priority` | The priority of the schedule (integer). Lower values represent higher priorities, with `0` indicating the highest priority.
+`schedule_type` | The type of task. The types are either an `Extract` for an extract refresh task or a `Subscription` for a scheduled subscription.
+`execution_order` | Specifies how the scheduled task should run. The choices are `Parallel`which uses all available background processes for this scheduled task, or `Serial`, which limits this schedule to one background process.
+`interval_item` | Specifies the frequency that the scheduled task should run. The `interval_item` is an instance of the `IntervalItem` class. The `interval_item` has properties for frequency (hourly, daily, weekly, monthly), and what time and date the scheduled item runs. You set this value by declaring an `IntervalItem` object that is one of the following: `HourlyInterval`, `DailyInterval`, `WeeklyInterval`, or `MonthlyInterval`.
+
+
+#### IntervalItem class
+This class sets the frequency and start time of the scheduled item. This class contains the classes for the hourly, daily, weekly, and monthly intervals. This class mirrors the options you can set using the REST API and the Tableau Server interface.
+
+**Attributes**
+
+Name | Description
+:--- | :---
+`HourlyInterval` | Runs scheduled item hourly. To set the hourly interval, you create an instance of the `HourlyInterval` class and assign the following values: `start_time`, `end_time`, and `interval_value`. To set the `start_time` and `end_time`, assign the time value using this syntax: `start_time=time(`*hour*`,` *minute*`)` and `end_time=time(`*hour*`,` *minute*`)`. The *hour* is specified in 24 hour time. The `interval_value` specifies how often the to run the task within the start and end time. The options are expressed in hours. For example, `interval_value=.25` is every 15 minutes. The values are `.25`, `.5`, `1`, `2`, `4`, `6`, `8`, `12`. Hourly schedules that run more frequently than every 60 minutes must have start and end times that are on the hour.
+`DailyInterval` | Runs the scheduled item daily. To set the daily interval, you create an instance of the `DailyInterval` and assign the `start_time`. The start time uses the syntax `start_time=time(`*hour*`,` *minute*`)`.
+`WeeklyInterval` | Runs the scheduled item once a week. To set the weekly interval, you create an instance of the `WeeklyInterval` and assign the start time and multiple instances for the `interval_value` (days of week and start time). The start time uses the syntax `time(`*hour*`,` *minute*`)`. The `interval_value` is the day of the week, expressed as a `IntervalItem`. For example `TSC.IntervalItem.Day.Monday` for Monday.
+`MonthlyInterval` | Runs the scheduled item once a month. To set the monthly interval, you create an instance of the `MonthlyInterval` and assign the start time and day. The
+
+
+
+
+### Schedule methods
+
+The schedule methods are based upon the endpoints for schedules in the REST API and operate on the `ScheduleItem` class.
+
+
+Source files: server/endpoint/schedules_endpoint.py
+
+#### schedules.add_to_schedule
+
+```py
+schedules.add_to_schedule(schedule_id, workbook=None, datasource=None, flow=None, task_type=None)
+```
+
+Adds a `DatasourceItem`, `FlowItem`, or `WorkbookItem` to a schedule.
+
+
+REST API: [Add Data Source to Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_data_source_to_schedule)
+
+
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`schedule_id` | The identifier (id) of the schedule to add the data source or workbook to. Can be retrieved from a `ScheduleItem`, e.g., by performing `schedules.get()`.
+`workbook` | (Optional) A `WorkbookItem` that should be added to the schedule. Only provide either `workbook` or `datasource`, passing multiple items will be deprecated.
+`datasource` | (Optional) A `DatasourceItem` that should be added to the schedule. Only provide either `workbook` or `datasource`, passing multiple items will be deprecated.
+`flow` | (Optional) A `FlowItem` that should be added to the schedule. Only applicable if `workbook = None` and `datasource = None`.
+`task_type` | (Optional) Determines the type of task. One of `TaskItem.Type`: `ExtractRefresh`, `DataAcceleration`, `RunFlow`.
+
+
+**Returns**
+Returns a List of `AddResponses`.
+
+
+**Example**
+
+```py
+import tableauserverclient as TSC
+# sign in, etc.
+# get a datasource item that should be added to a schedule
+datasource_item = server.datasources.get("d14dd951-01c1-4879-8bc2-e96d7dec9f0")
+
+# retrieve the id of the target schedule
+schedule_id = schedule_item.id # can be a freshly created schedule or one queried via `schedules.get()`
+
+# Add the data source to the schedule
+server.schedules.add_to_schedule(
+ schedule_id=schedule_id,
+ datasource=datasource_item,
+)
+```
+
+
+
+
+#### schedules.create
+
+```py
+schedules.create(schedule_item)
+```
+Creates a new schedule for an extract refresh or a subscription.
+
+
+REST API: [Create Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_schedule)
+
+
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`schedule_item` | The settings for the schedule that you want to create. You need to create an instance of `ScheduleItem` and pass it to the `create` method. The `ScheduleItem` includes the `IntervalItem` which specifies the frequency, or interval, that the schedule should run.
+
+
+**Returns**
+
+Returns a new instance of `schedule_item`.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`Interval item must be defined.` | Raises an exception if the `schedule_item.interval_item` is not specified. The interval item specifies whether the interval is hourly, daily, weekly, or monthly.
+
+
+**Example**
+
+```py
+import tableauserverclient as TSC
+from datetime import time
+
+# sign in, etc.
+# Create an interval to run every 2 hours between 2:30AM and 11:00PM
+hourly_interval = TSC.HourlyInterval(start_time=time(2, 30),
+ end_time=time(23, 0),
+ interval_value=2)
+# Create schedule item
+hourly_schedule = TSC.ScheduleItem("Hourly-Schedule",
+ 50,
+ TSC.ScheduleItem.Type.Extract,
+ TSC.ScheduleItem.ExecutionOrder.Parallel,
+ hourly_interval)
+# Create schedule
+hourly_schedule = server.schedules.create(hourly_schedule)
+```
+
+
+
+
+#### schedules.delete
+
+```py
+schedules.delete(schedule_id)
+```
+
+Deletes an existing schedule for an extract refresh or a subscription.
+
+
+REST API: [Delete Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_schedule)
+
+
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`schedule_id` | The identifier (`schedule_item.id`) of the schedule to delete. Use the `schedule.get()` method to get the identifiers of the schedules on the server.
+
+
+**Returns**
+
+None.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`Schedule ID undefined` | The identifier is not a valid identifier for a schedule on the server.
+
+
+#### schedules.get
+
+```py
+schedules.get()
+```
+
+Returns all schedule items from the server.
+
+
+REST API: [Query Schedules](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_schedules)
+
+
+#### schedules.get_by_id
+
+```py
+schedules.get_by_id(schedule_id)
+```
+
+Returns the specified schedule.
+
+
+REST API: [Get Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get-schedule)
+
+
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`req_options` | (Optional) Additional request options to send to the endpoint.
+
+#### schedules.update
+
+```py
+schedules.update(schedule_item)
+```
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`schedule_item` | The settings for the schedule that you want to update. You need to fetch an existing instance of `ScheduleItem` from the `get` method, make your changes, and then pass it to the `update` method to update the schedule on the server. The `ScheduleItem` includes the `IntervalItem` which specifies the frequency, or interval, that the schedule should run.
+
+
+REST API: [Update Schedules](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_schedule)
+
+
+
+
+
+**Hourly schedule example**
+```py
+import tableauserverclient as TSC
+from datetime import time
+# sign in, etc.
+
+# Create an interval to run every 2 hours between 2:30AM and 11:00PM
+hourly_interval = TSC.HourlyInterval(start_time=time(2, 30),
+ end_time=time(23, 0),
+ interval_value=2)
+
+# Create schedule item
+hourly_schedule = TSC.ScheduleItem("Hourly-Schedule",
+ 50,
+ TSC.ScheduleItem.Type.Extract,
+ TSC.ScheduleItem.ExecutionOrder.Parallel,
+ hourly_interval)
+
+# Create schedule
+hourly_schedule = server.schedules.create(hourly_schedule)
+```
+
+**Daily schedule example**
+```py
+import tableauserverclient as TSC
+from datetime import time
+# sign in, etc.
+
+# Create a daily interval to run every day at 12:30AM
+daily_interval = TSC.DailyInterval(start_time=time(0, 30))
+
+# Create schedule item using daily interval
+daily_schedule = TSC.ScheduleItem("Daily-Schedule",
+ 60,
+ TSC.ScheduleItem.Type.Subscription,
+ TSC.ScheduleItem.ExecutionOrder.Serial,
+ daily_interval)
+
+# Create daily schedule
+daily_schedule = server.schedules.create(daily_schedule)
+```
+
+**Weekly schedule example**
+```py
+import tableauserverclient as TSC
+from datetime import time
+# sign in, etc.
+
+# Create a weekly interval to run every Monday, Wednesday, and Friday at 7:15PM
+weekly_interval = TSC.WeeklyInterval(time(19, 15),
+ TSC.IntervalItem.Day.Monday,
+ TSC.IntervalItem.Day.Wednesday,
+ TSC.IntervalItem.Day.Friday)
+# Create schedule item using weekly interval
+weekly_schedule = TSC.ScheduleItem("Weekly-Schedule", 70,
+ TSC.ScheduleItem.Type.Extract,
+ TSC.ScheduleItem.ExecutionOrder.Serial,
+ weekly_interval)
+# Create weekly schedule
+weekly_schedule = server.schedules.create(weekly_schedule)
+```
+
+**Monthly schedule example**
+```py
+import tableauserverclient as TSC
+from datetime import time
+# sign in, etc.
+
+# Create a monthly interval to run on the 15th of every month at 11:30PM
+monthly_interval = TSC.MonthlyInterval(start_time=time(23, 30),
+ interval_value=15)
+# Create schedule item using monthly interval
+monthly_schedule = TSC.ScheduleItem("Monthly-Schedule",
+ 80,
+ TSC.ScheduleItem.Type.Subscription
+ TSC.ScheduleItem.ExecutionOrder.Parallel, monthly_interval)
+# Create monthly schedule
+monthly_schedule = server.schedules.create(monthly_schedule)
+```
+
+#### schedules.batch_update_state
+
+```py
+schedules.batch_update_state(schedules, state, update_all=False)
+```
+
+Batch update the status of one or more schedules. If `update_all` is set to `True`, all schedules on the Tableau Server are affected.
+
+REST API: [Batch Update Schedule State](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#batch_update_schedule_state)
+
+**Version**
+
+This endpoint is available with REST API version 3.27 and up.
+
+**Parameters**
+
+| Name | Description |
+| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| `schedules` | (Optional) An iterable of `ScheduleItem` objects or schedule ID strings to be updated. If `update_all=True`, this parameter is ignored. |
+| `state` | The state to set for the schedules. Must be either `"active"` or `"suspended"`. |
+| `update_all` | (Optional) If set to `True`, applies the state to all schedules on the server. Defaults to `False`. |
+
+**Returns**
+
+A list of strings containing the IDs of the affected schedules.
+
+**Example**
+
+```py
+import tableauserverclient as TSC
+# sign in, etc.
+
+# Get schedules to update
+schedules, pagination = server.schedules.get()
+schedules_to_update = [schedules[0], schedules[1], schedules[2]]
+
+# Batch update schedules to active state
+affected_ids = server.schedules.batch_update_state(schedules_to_update, "active")
+
+# Or update using schedule ID strings
+schedule_ids = ["593d2ebf-0d18-4deb-9d21-b113a4902583",
+ "cecbb71e-def0-4030-8068-5ae50f51db1c"]
+affected_ids = server.schedules.batch_update_state(schedule_ids, "suspended")
+
+# Update all schedules on the server
+all_affected_ids = server.schedules.batch_update_state([], "active", update_all=True)
+```
+
+
+
+
+
+---
+
+
+## Server
+
+In the Tableau REST API, the server (`https://MY-SERVER/`) is the base or core of the URI that makes up the various endpoints or methods for accessing resources on the server (views, workbooks, sites, users, data sources, etc.)
+The TSC library provides a `Server` class that represents the server. You create a server instance to sign in to the server and to call the various methods for accessing resources.
+
+
+
+
+
+
+### Server class
+
+```py
+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**
+
+Attribute | Description
+:--- | :---
+`server_address` | Specifies the address of the Tableau Server or Tableau Cloud (for example, `https://MY-SERVER/`).
+`version` | Specifies the version of the REST API to use (for example, `'2.5'`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to `'2.3'`, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+
+
+
+**Example**
+
+```py
+import tableauserverclient as TSC
+
+
+# create a instance of server
+server = TSC.Server('https://MY-SERVER')
+
+# sign in, etc.
+
+# change the REST API version to match the server
+server.use_server_version()
+
+# or change the REST API version to match a specific version
+# for example, 2.8
+# server.version = '2.8'
+
+```
+
+#### Server.*Resources*
+
+When you create an instance of the `Server` class, you have access to the resources on the server after you sign in. You can select these resources and their methods as members of the class, for example: `server.views.get()`
+
+
+
+Resource | Description
+ :--- | : ---
+*server*.auth | Sets authentication for sign in and sign out. See [Auth](#authentication) |
+*server*.views | Access the server views and methods. See [Views](#views)
+*server*.users | Access the user resources and methods. See [Users](#users)
+*server*.sites | Access the sites. See [Sites](#sites)
+*server*.groups | Access the groups resources and methods. See [Groups](#groups)
+*server*.jobs | Access the jobs resources and methods. See [Jobs](#jobs)
+*server*.workbooks | Access the resources and methods for workbooks. See [Workbooks](#workbooks)
+*server*.datasources | Access the resources and methods for data sources. See [Data Sources](#data-sources)
+*server*.projects | Access the resources and methods for projects. See [Projects](#projects)
+*server*.schedules | Access the resources and methods for schedules. See [Schedules](#schedules)
+*server*.subscriptions | Access the resources and methods for subscriptions. See [Subscriptions](#subscriptions)
+*server*.server_info | Access the resources and methods for server information. See [ServerInfo class](#serverinfoitem-class)
+
+
+
+
+#### Server.PublishMode
+
+The `Server` class has `PublishMode` class that enumerates the options that specify what happens when you publish a workbook or data source. The options are `Overwrite`, `Append`, or `CreateNew`.
+
+
+**Properties**
+
+Resource | Description
+ :--- | : ---
+`PublishMode.Overwrite` | Overwrites the workbook or data source.
+`PublishMode.Append` | Appends to the workbook or data source.
+`PublishMode.CreateNew` | Creates a new workbook or data source.
+
+
+**Example**
+
+```py
+ import tableauserverclient as TSC
+ # login, etc.
+ print(TSC.Server.PublishMode.Overwrite)
+ # prints 'Overwrite'
+ overwrite_true = TSC.Server.PublishMode.Overwrite
-#### RequestOptions.Direction class
+ ...
-Specifies the direction to sort the returned fields.
+ # pass the PublishMode to the publish workbooks method
+ new_workbook = server.workbooks.publish(new_workbook, args.filepath, overwrite_true)
-**Attributes**
+```
-Name | Description
-:--- | :---
-`Asc` | Sets the sort direction to ascending (`TSC.RequestOptions.Direction.Asc`)
-`Desc` | Sets the sort direction to descending (`TSC.RequestOptions.Direction.Desc`).
-### CSVRequestOptions class
+
+### ServerInfoItem class
```py
-CSVRequestOptions(maxage=-1)
+ServerInfoItem(product_version, build_number, rest_api_version)
```
-Use this class to specify view filters to be applied when the CSV data is generated. Optionally, you can specify the maximum age of the CSV data cached on the server by providing a `maxage` value. See `views.populate_csv`.
+The `ServerInfoItem` class contains the build and version information for Tableau Server. The server information is accessed with the `server_info.get()` method, which returns an instance of the `ServerInfo` class.
**Attributes**
Name | Description
:--- | :---
-`maxage` | Optional. The maximum number of minutes the CSV data will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
+`product_version` | Shows the version of the Tableau Server or Tableau Cloud (for example, 10.2.0).
+`build_number` | Shows the specific build number (for example, 10200.17.0329.1446).
+`rest_api_version` | Shows the supported REST API version number. Note that this might be different from the default value specified for the server, with the `Server.version` attribute. To take advantage of new features, you should query the server and set the `Server.version` to match the supported REST API version number.
-**Example**
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
+
+
-# set view filters
-csv_req_option = TSC.CSVRequestOptions(maxage=5)
-csv_req_option.vf('Region', 'South')
-csv_req_option.vf('Category', 'Furniture')
-# retrieve the csv data for the view
-server.views.populate_csv(view_item, csv_req_option)
-```
+### ServerInfo methods
-If you set a parameter in the workbook, you can also pass the parameter value as part of the `CSVRequestOptions` object. For example, if you have a parameter named `Region` in the workbook, you can set the parameter value to `South` as follows:
+The TSC library provides a method to access the build and version information from Tableau Server.
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
+
-# set view filters
-csv_req_option = TSC.CSVRequestOptions(maxage=5)
-csv_req_option.parameter('Region', 'South')
+#### server_info.get
+
+```py
+server_info.get()
-# retrieve the csv data for the view
-server.views.populate_csv(view_item, csv_req_option)
```
+Retrieve the build and version information for the server.
-### ExcelRequestOptions class
+This method makes an unauthenticated call, so no sign in or authentication token is required.
-```py
-ExcelRequestOptions(maxage=-1)
-```
-Use this class to specify view filters to be applied when data is generated in an Excel file format. Optionally, you can specify the maximum age of the Excel data cached on the server by providing a `maxage` value. See `views.populate_csv`.
+REST API: [Server Info](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#server_info)
-**Attributes**
+**Parameters**
+ None
-Name | Description
+**Exceptions**
+
+Error | Description
:--- | :---
-`maxage` | Optional. The maximum number of minutes the Excel data will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
+`404003 UNKNOWN_RESOURCE` | Raises an exception if the server info endpoint is not found.
**Example**
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
+import tableauserverclient as TSC
-# set view filters
-excel_req_option = TSC.ExcelRequestOptions(maxage=5)
-excel_req_option.vf('Region', 'South')
-excel_req_option.vf('Category', 'Furniture')
+# create a instance of server
+server = TSC.Server('https://MY-SERVER')
+
+# set the version number > 2.3
+# the server_info.get() method works in 2.4 and later
+server.version = '2.5'
+
+s_info = server.server_info.get()
+print("\nServer info:")
+print("\tProduct version: {0}".format(s_info.product_version))
+print("\tREST API version: {0}".format(s_info.rest_api_version))
+print("\tBuild number: {0}".format(s_info.build_number))
-# retrieve the excel data for the view
-server.views.populate_excel(view_item, excel_req_option)
```
-If you set a parameter in the workbook, you can also pass the parameter value as part of the `ExcelRequestOptions` object. For example, if you have a parameter named `Region` in the workbook, you can set the parameter value to `South` as follows:
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
+
+
-# set view filters
-excel_req_option = TSC.ExcelRequestOptions(maxage=5)
-excel_req_option.parameter('Region', 'South')
+---
-# retrieve the excel data for the view
-server.views.populate_excel(view_item, excel_req_option)
-```
+## Sites
-### ImageRequestOptions class
+Using the TSC library, you can query a site or sites on a server, or create or delete a site on the server.
+
+The site resources for Tableau Server and Tableau Cloud are defined in the `SiteItem` class. The class corresponds to the site resources you can access using the Tableau Server REST API. The site methods are based upon the endpoints for sites in the REST API and operate on the `SiteItem` class.
+
+
+
+
+### SiteItem class
```py
-ImageRequestOptions(imageresolution=None, maxage=-1)
+SiteItem(name, content_url, admin_mode=None, user_quota=None, storage_quota=None,
+ disable_subscriptions=False, subscribe_others_enabled=True, revision_history_enabled=False)
```
-Use this class to specify the resolution of the view and, optionally, the maximum age of the image cached on the server. You can also use this class to specify view filters to be applied when the image is generated. See `views.populate_image`.
+
+The `SiteItem` class contains the members or attributes for the site resources on Tableau Server or Tableau Cloud. The `SiteItem` class defines the information you can request or query from Tableau Server or Tableau Cloud. The class members correspond to the attributes of a server request or response payload.
**Attributes**
-Name | Description
+Attribute | Description
:--- | :---
-`imageresolution` | The resolution of the view returned as an image. If unspecified, the `views.populate_image` method returns an image with standard resolution (the width of the returned image is 784 pixels). If you set this parameter value to high (`Resolution.High`), the width of the returned image is 1568 pixels. For both resolutions, the height varies to preserve the aspect ratio of the view.
-`maxage` | Optional. The maximum number of minutes the image will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
-
-**View Filters**
+`name` | The name of the site. The name of the default site is "".
+`content_url` | The path to the site.
+`admin_mode` | (Optional) For Tableau Server only. Specify `ContentAndUsers` to allow site administrators to use the server interface and **tabcmd** commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify `ContentOnly` to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.)
+`user_quota`| (Optional) Specifies the total number of users for the site. The number can't exceed the number of licenses activated for the site; and if tiered capacity attributes are set, then `user_quota` will equal the sum of the tiered capacity values, and attempting to set `user_quota` will cause an error.
+Tiered capacity attributes: `tier_explorer_capacity` `tier_creator_capacity` `tier_viewer_capacity`| (Optional) The maximum number of licenses for users with the Creator, Explorer, or Viewer role, respectively, allowed on a site.
+`storage_quota` | (Optional) Specifies the maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again.
+`disable_subscriptions` | (Optional) Specify `true` to prevent users from being able to subscribe to workbooks on the specified site. The default is `false`.
+`subscribe_others_enabled` | (Optional) Specify `false` to prevent server administrators, site administrators, and project or content owners from being able to subscribe other users to workbooks on the specified site. The default is `true`.
+`revision_history_enabled` | (Optional) Specify `true` to enable revision history for content resources (workbooks and datasources). The default is `false`.
+`revision_limit` | (Optional) Specifies the number of revisions of a content source (workbook or data source) to allow. On Tableau Server, the default is 25.
+`state` | Shows the current state of the site (`Active` or `Suspended`).
-You can use the `vf('filter_name', 'filter_value')` method to add view filters. When the image is generated, the specified filters will be applied to the view.
**Example**
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
-
-# set the image request option
-image_req_option = TSC.ImageRequestOptions(imageresolution=TSC.ImageRequestOptions.Resolution.High, maxage=1)
-# (optional) set a view filter
-image_req_option.vf('Category', 'Furniture')
+# create a new instance of a SiteItem
-# retrieve the image for the view
-server.views.populate_image(view_item, image_req_option)
+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
-If you set a parameter in the workbook, you can also pass the parameter value as part of the `ImageRequestOptions` object. For example, if you have a parameter named `Region` in the workbook, you can set the parameter value to `South` as follows:
-
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
-
-# set view filters
-image_req_option = TSC.ImageRequestOptions(maxage=5)
-image_req_option.parameter('Region', 'South')
+
+
-# retrieve the image data for the view
-server.views.populate_image(view_item, image_req_option)
-```
-### PDFRequestOptions class
+### SiteAuthConfiguration class
-```py
-PDFRequestOptions(page_type=None, orientation=None, maxage=-1)
-```
-Use this class to specify the format of the PDF that is returned for the view. Optionally, you can specify the maximum age of the rendered PDF that is cached on the server by providing a `maxage` value. See `views.populate_pdf`.
+The `SiteAuthConfiguration` class contains the attributes for the authentication configuration on Tableau Cloud. This class represents the authentication configuration information returned when using the `sites.list_auth_configurations` method.
**Attributes**
-Name | Description
+Attribute | Description
:--- | :---
-`page_type` | The type of page returned in PDF format for the view. The page_type is set using the `PageType` class:
`PageType.A3`
`PageType.A4`
`PageType.A5`
`PageType.B5`
`PageType.Executive`
`PageType.Folio`
`PageType.Ledger`
`PageType.Legal`
`PageType.Letter`
`PageType.Note`
`PageType.Quarto`
`PageType.Tabloid`
`PageType.Unspecified`
-`orientation` | The orientation of the page. The options are portrait and landscape. The options are set using the `Orientation` class:
`Orientation.Portrait`
`Orientation.Landscape`
-`maxage` | Optional. The maximum number of minutes the rendered PDF will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
-`viz_height` | Optional. The height of the output PDF in pixels. If specified, viz_width must also be specified.
-`viz_width` | Optional. The width of the output PDF in pixels. If specified, viz_height must also be specified.
-
-**View Filters**
-You can use the `vf('filter_name', 'filter_value')` method to add view filters. When the PDF is generated, the specified filters will be applied to the view.
+`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**
```py
# import tableauserverclient as TSC
# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
+# sign in, etc.
-# set the PDF request options
-pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4,
- orientation=TSC.PDFRequestOptions.Orientation.Landscape,
- maxage=1)
+# Get authentication configurations for the current site
+auth_configs = server.sites.list_auth_configurations()
-# (optional) set a view filter
-pdf_req_option.vf('Region', 'West')
+# Display configuration details
+for config in auth_configs:
+ print(f"ID: {config.idp_configuration_id}")
+ print(f"Name: {config.idp_configuration_name}")
+ print(f"Type: {config.auth_setting}")
+ print(f"Enabled: {config.enabled}")
+ print(f"Provider: {config.known_provider_alias}")
+```
-# retrieve the PDF for a view
-server.views.populate_pdf(view_item, pdf_req_option)
+
+
-```
+### Site methods
+The TSC library provides methods that operate on sites for Tableau Server and Tableau Cloud. These methods correspond to endpoints or methods for sites in the Tableau REST API.
-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.
+
+Source file: server/endpoint/sites_endpoint.py
+
+
+
+
+#### sites.create
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
+sites.create(site_item)
+```
-# set the PDF request options
-pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4,
- orientation=TSC.PDFRequestOptions.Orientation.Landscape,
- maxage=1,
- viz_height=800,
- viz_width=1200)
+Creates a new site on the server for the specified site item object.
-server.views.populate_pdf(view_item, pdf_req_option)
+Tableau Server only.
+
+
+REST API: [Create Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_site)
+
+
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`site_item` | The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass it to the `create` method.
-```
-If you set a parameter in the workbook, you can also pass the parameter value as part of the `PDFRequestOptions` object. For example, if you have a parameter named `Region` in the workbook, you can set the parameter value to `South` as follows:
+**Returns**
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, get a specific view, etc.
+Returns a new instance of `SiteItem`.
-# set view filters
-pdf_req_option = TSC.PDFRequestOptions(maxage=5)
-pdf_req_option.parameter('Region', 'South')
-# retrieve the pdf data for the view
-server.views.populate_pdf(view_item, pdf_req_option)
-```
+**Example**
-
-
+```py
+import tableauserverclient as TSC
----
+# create an instance of server
+server = TSC.Server('https://MY-SERVER')
-## Schedules
+# create shortcut for admin mode
+content_users=TSC.SiteItem.AdminMode.ContentAndUsers
-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.
+# 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)
-If you have the identifier of the job, you can use the TSC library to find out the status of the asynchronous job.
+# call the sites create method with the SiteItem
+new_site = server.sites.create(new_site)
+```
+
+
-The schedule properties are defined in the `ScheduleItem` class. The class corresponds to the properties for schedules you can access in Tableau Server or by using the Tableau Server REST API. The Schedule methods are based upon the endpoints for jobs in the REST API and operate on the `JobItem` class.
+#### sites.get
+```py
+sites.get()
+```
-### ScheduleItem class
+Queries all the sites on the server.
-```py
-ScheduleItem(name, priority, schedule_type, execution_order, interval_item)
-```
+REST API: [Query Sites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_sites)
-The `ScheduleItem` class contains information about the specified schedule running on Tableau Server. The `ScheduleItem` class defines the information you can query and set. The class members correspond to the attributes of a server response payload.
-Source file: models/schedule_item.py
+**Parameters**
-**Attributes**
+ None.
-Name | Description
-:--- | :---
-`name` | The `name` of the schedule.
-`priority` | The priority of the schedule (integer). Lower values represent higher priorities, with `0` indicating the highest priority.
-`schedule_type` | The type of task. The types are either an `Extract` for an extract refresh task or a `Subscription` for a scheduled subscription.
-`execution_order` | Specifies how the scheduled task should run. The choices are `Parallel`which uses all available background processes for this scheduled task, or `Serial`, which limits this schedule to one background process.
-`interval_item` | Specifies the frequency that the scheduled task should run. The `interval_item` is an instance of the `IntervalItem` class. The `interval_item` has properties for frequency (hourly, daily, weekly, monthly), and what time and date the scheduled item runs. You set this value by declaring an `IntervalItem` object that is one of the following: `HourlyInterval`, `DailyInterval`, `WeeklyInterval`, or `MonthlyInterval`.
+**Returns**
+Returns a list of all `SiteItem` objects and a `PaginationItem`. Use these values to iterate through the results.
-#### IntervalItem class
-This class sets the frequency and start time of the scheduled item. This class contains the classes for the hourly, daily, weekly, and monthly intervals. This class mirrors the options you can set using the REST API and the Tableau Server interface.
-**Attributes**
+**Example**
-Name | Description
-:--- | :---
-`HourlyInterval` | Runs scheduled item hourly. To set the hourly interval, you create an instance of the `HourlyInterval` class and assign the following values: `start_time`, `end_time`, and `interval_value`. To set the `start_time` and `end_time`, assign the time value using this syntax: `start_time=time(`*hour*`,` *minute*`)` and `end_time=time(`*hour*`,` *minute*`)`. The *hour* is specified in 24 hour time. The `interval_value` specifies how often the to run the task within the start and end time. The options are expressed in hours. For example, `interval_value=.25` is every 15 minutes. The values are `.25`, `.5`, `1`, `2`, `4`, `6`, `8`, `12`. Hourly schedules that run more frequently than every 60 minutes must have start and end times that are on the hour.
-`DailyInterval` | Runs the scheduled item daily. To set the daily interval, you create an instance of the `DailyInterval` and assign the `start_time`. The start time uses the syntax `start_time=time(`*hour*`,` *minute*`)`.
-`WeeklyInterval` | Runs the scheduled item once a week. To set the weekly interval, you create an instance of the `WeeklyInterval` and assign the start time and multiple instances for the `interval_value` (days of week and start time). The start time uses the syntax `time(`*hour*`,` *minute*`)`. The `interval_value` is the day of the week, expressed as a `IntervalItem`. For example `TSC.IntervalItem.Day.Monday` for Monday.
-`MonthlyInterval` | Runs the scheduled item once a month. To set the monthly interval, you create an instance of the `MonthlyInterval` and assign the start time and day. The
+```py
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, etc.
+ # query the sites
+ all_sites, pagination_item = server.sites.get()
+ # print all the site names and ids
+ for site in all_sites:
+ print(site.id, site.name, site.content_url, site.state)
-### Schedule methods
+```
-The schedule methods are based upon the endpoints for schedules in the REST API and operate on the `ScheduleItem` class.
+
+
-Source files: server/endpoint/schedules_endpoint.py
-#### schedules.add_to_schedule
+#### sites.get_by_id
```py
-schedules.add_to_schedule(schedule_id, workbook=None, datasource=None, flow=None, task_type=None)
+sites.get_by_id(site_id)
```
-Adds a `DatasourceItem`, `FlowItem`, or `WorkbookItem` to a schedule.
-
-
-REST API: [Add Data Source to Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_data_source_to_schedule)
+Queries the site with the given ID.
+REST API: [Query Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_site)
**Parameters**
Name | Description
:--- | :---
-`schedule_id` | The identifier (id) of the schedule to add the data source or workbook to. Can be retrieved from a `ScheduleItem`, e.g., by performing `schedules.get()`.
-`workbook` | (Optional) A `WorkbookItem` that should be added to the schedule. Only provide either `workbook` or `datasource`, passing multiple items will be deprecated.
-`datasource` | (Optional) A `DatasourceItem` that should be added to the schedule. Only provide either `workbook` or `datasource`, passing multiple items will be deprecated.
-`flow` | (Optional) A `FlowItem` that should be added to the schedule. Only applicable if `workbook = None` and `datasource = None`.
-`task_type` | (Optional) Determines the type of task. One of `TaskItem.Type`: `ExtractRefresh`, `DataAcceleration`, `RunFlow`.
+`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 a List of `AddResponses`.
+
+Returns the `SiteItem`.
**Example**
```py
-import tableauserverclient as TSC
+
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
-# get a datasource item that should be added to a schedule
-datasource_item = server.datasources.get("d14dd951-01c1-4879-8bc2-e96d7dec9f0")
-# retrieve the id of the target schedule
-schedule_id = schedule_item.id # can be a freshly created schedule or one queried via `schedules.get()`
+ 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))
-# Add the data source to the schedule
-server.schedules.add_to_schedule(
- schedule_id=schedule_id,
- datasource=datasource_item,
-)
```
+
-
-#### schedules.create
+#### sites.get_by_name
```py
-schedules.create(schedule_item)
+sites.get_by_name(site_name)
```
-Creates a new schedule for an extract refresh or a subscription.
-
-REST API: [Create Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_schedule)
+Queries the site with the specified name.
+REST API: [Query Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_site)
**Parameters**
Name | Description
:--- | :---
-`schedule_item` | The settings for the schedule that you want to create. You need to create an instance of `ScheduleItem` and pass it to the `create` method. The `ScheduleItem` includes the `IntervalItem` which specifies the frequency, or interval, that the schedule should run.
+`site_name` | The name of the site you want to query.
-**Returns**
+**Exceptions**
-Returns a new instance of `schedule_item`.
+Error | Description
+ :--- | : ---
+`Site Name undefined.` | Raises an error if an name is not specified.
-**Exceptions**
-Error | Description
-:--- | :---
-`Interval item must be defined.` | Raises an exception if the `schedule_item.interval_item` is not specified. The interval item specifies whether the interval is hourly, daily, weekly, or monthly.
+**Returns**
+
+Returns the `SiteItem`.
**Example**
```py
-import tableauserverclient as TSC
-from datetime import time
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
-# Create an interval to run every 2 hours between 2:30AM and 11:00PM
-hourly_interval = TSC.HourlyInterval(start_time=time(2, 30),
- end_time=time(23, 0),
- interval_value=2)
-# Create schedule item
-hourly_schedule = TSC.ScheduleItem("Hourly-Schedule",
- 50,
- TSC.ScheduleItem.Type.Extract,
- TSC.ScheduleItem.ExecutionOrder.Parallel,
- hourly_interval)
-# Create schedule
-hourly_schedule = server.schedules.create(hourly_schedule)
+
+ a_site = server.sites.get_by_name('MY_SITE')
+
+
```
+
-#### schedules.delete
+
+#### sites.update
```py
-schedules.delete(schedule_id)
+sites.update(site_item)
```
-Deletes an existing schedule for an extract refresh or a subscription.
+Modifies the settings for site.
-REST API: [Delete Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_schedule)
+The site item object must include the site ID and overrides all other settings.
+
+REST API: [Update Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_site)
**Parameters**
Name | Description
:--- | :---
-`schedule_id` | The identifier (`schedule_item.id`) of the schedule to delete. Use the `schedule.get()` method to get the identifiers of the schedules on the server.
-
-
-**Returns**
+`site_item` | The site item that you want to update. The settings specified in the site item override the current site settings.
-None.
**Exceptions**
-Error | Description
+Error | Description
:--- | :---
-`Schedule ID undefined` | The identifier is not a valid identifier for a schedule on the server.
+`Site item missing ID.` | The site id must be present and must match the id of the site you are updating.
+`You cannot set admin_mode to ContentOnly and also set a user quota` | To set the `user_quota`, the `AdminMode` must be set to `ContentAndUsers`
-#### schedules.get
+**Returns**
+
+Returns the updated `site_item`.
+
+
+**Example**
```py
-schedules.get()
+...
+
+# make some updates to an existing site_item
+site_item.name ="New name"
+
+# call update
+site_item = server.sites.update(site_item)
+
+...
```
-Returns all schedule items from the server.
+
+
-REST API: [Query Schedules](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_schedules)
-#### schedules.get_by_id
+#### sites.delete
+
```py
-schedules.get_by_id(schedule_id)
+Sites.delete(site_id)
```
-Returns the specified schedule.
-
+Deletes the specified site.
-REST API: [Get Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get-schedule)
+REST API: [Delete Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_site)
**Parameters**
-Name | Description
-:--- | :---
-`req_options` | (Optional) Additional request options to send to the endpoint.
+Name | Description
+ :--- | : ---
+`site_id` | The id of the site that you want to delete.
-#### schedules.update
-```py
-schedules.update(schedule_item)
-```
-**Parameters**
+**Exceptions**
-Name | Description
-:--- | :---
-`schedule_item` | The settings for the schedule that you want to update. You need to fetch an existing instance of `ScheduleItem` from the `get` method, make your changes, and then pass it to the `update` method to update the schedule on the server. The `ScheduleItem` includes the `IntervalItem` which specifies the frequency, or interval, that the schedule should run.
+Error | Description
+:--- | :---
+`Site ID Undefined.` | The site id must be present and must match the id of the site you are deleting.
-REST API: [Update Schedules](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_schedule)
+
+**Example**
+
+```py
+
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
+# sign in, etc.
+
+server.sites.delete('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')
+
+```
+#### sites.list_auth_configurations
-**Hourly schedule example**
```py
-import tableauserverclient as TSC
-from datetime import time
-# sign in, etc.
-
-# Create an interval to run every 2 hours between 2:30AM and 11:00PM
-hourly_interval = TSC.HourlyInterval(start_time=time(2, 30),
- end_time=time(23, 0),
- interval_value=2)
-
-# Create schedule item
-hourly_schedule = TSC.ScheduleItem("Hourly-Schedule",
- 50,
- TSC.ScheduleItem.Type.Extract,
- TSC.ScheduleItem.ExecutionOrder.Parallel,
- hourly_interval)
-
-# Create schedule
-hourly_schedule = server.schedules.create(hourly_schedule)
+sites.list_auth_configurations()
```
-**Daily schedule example**
-```py
-import tableauserverclient as TSC
-from datetime import time
-# sign in, etc.
-
-# Create a daily interval to run every day at 12:30AM
-daily_interval = TSC.DailyInterval(start_time=time(0, 30))
+Lists the authentication configurations for the current site.
-# Create schedule item using daily interval
-daily_schedule = TSC.ScheduleItem("Daily-Schedule",
- 60,
- TSC.ScheduleItem.Type.Subscription,
- TSC.ScheduleItem.ExecutionOrder.Serial,
- daily_interval)
+REST API: [List Authentication Configurations for the current Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_site.htm#list_auth_configurations_site)
-# Create daily schedule
-daily_schedule = server.schedules.create(daily_schedule)
-```
+**Returns**
-**Weekly schedule example**
-```py
-import tableauserverclient as TSC
-from datetime import time
-# sign in, etc.
+Returns a list of authentication configurations for the current site.
-# Create a weekly interval to run every Monday, Wednesday, and Friday at 7:15PM
-weekly_interval = TSC.WeeklyInterval(time(19, 15),
- TSC.IntervalItem.Day.Monday,
- TSC.IntervalItem.Day.Wednesday,
- TSC.IntervalItem.Day.Friday)
-# Create schedule item using weekly interval
-weekly_schedule = TSC.ScheduleItem("Weekly-Schedule", 70,
- TSC.ScheduleItem.Type.Extract,
- TSC.ScheduleItem.ExecutionOrder.Serial,
- weekly_interval)
-# Create weekly schedule
-weekly_schedule = server.schedules.create(weekly_schedule)
-```
+**Example**
-**Monthly schedule example**
```py
-import tableauserverclient as TSC
-from datetime import time
+# import tableauserverclient as TSC
+# server = TSC.Server('https://MY-SERVER')
# sign in, etc.
-# Create a monthly interval to run on the 15th of every month at 11:30PM
-monthly_interval = TSC.MonthlyInterval(start_time=time(23, 30),
- interval_value=15)
-# Create schedule item using monthly interval
-monthly_schedule = TSC.ScheduleItem("Monthly-Schedule",
- 80,
- TSC.ScheduleItem.Type.Subscription
- TSC.ScheduleItem.ExecutionOrder.Parallel, monthly_interval)
-# Create monthly schedule
-monthly_schedule = server.schedules.create(monthly_schedule)
+auth_configs = server.sites.list_auth_configurations()
+for config in auth_configs:
+ print(f"IDP Configuration ID: {config.idp_configuration_id}")
+ print(f"Name: {config.idp_configuration_name}")
+ print(f"Type: {config.auth_setting}")
+ print(f"Enabled: {config.enabled}")
```
-#### schedules.batch_update_state
+
+
+
+#### sites.get_by_content_url
```py
-schedules.batch_update_state(schedules, state, update_all=False)
+sites.get_by_content_url(content_url)
```
-Batch update the status of one or more schedules. If `update_all` is set to `True`, all schedules on the Tableau Server are affected.
-
-REST API: [Batch Update Schedule State](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#batch_update_schedule_state)
-
-**Version**
+Returns the site with the specified content URL.
-This endpoint is available with REST API version 3.27 and up.
+REST API: [Query Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_site.htm#query_site){:target="_blank"}
**Parameters**
-| Name | Description |
-| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
-| `schedules` | (Optional) An iterable of `ScheduleItem` objects or schedule ID strings to be updated. If `update_all=True`, this parameter is ignored. |
-| `state` | The state to set for the schedules. Must be either `"active"` or `"suspended"`. |
-| `update_all` | (Optional) If set to `True`, applies the state to all schedules on the server. Defaults to `False`. |
+Name | Description
+:--- | :---
+`content_url` | The `content_url` for the site to query. This is the `contentUrl` value in the REST API and corresponds to the portion of the URL after `/site/` (for example, `"MarketingTeam"`). Use an empty string for the default site.
**Returns**
-A list of strings containing the IDs of the affected schedules.
+Returns a `SiteItem`.
+
+**Version**
+
+Version 2.0 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-import tableauserverclient as TSC
-# sign in, etc.
-
-# Get schedules to update
-schedules, pagination = server.schedules.get()
-schedules_to_update = [schedules[0], schedules[1], schedules[2]]
+site = server.sites.get_by_content_url('MarketingTeam')
+print(site.id, site.name)
+```
-# Batch update schedules to active state
-affected_ids = server.schedules.batch_update_state(schedules_to_update, "active")
+
+
-# Or update using schedule ID strings
-schedule_ids = ["593d2ebf-0d18-4deb-9d21-b113a4902583",
- "cecbb71e-def0-4030-8068-5ae50f51db1c"]
-affected_ids = server.schedules.batch_update_state(schedule_ids, "suspended")
+#### sites.encrypt_extracts
-# Update all schedules on the server
-all_affected_ids = server.schedules.batch_update_state([], "active", update_all=True)
+```py
+sites.encrypt_extracts(site_id)
```
+Encrypts all extracts on the specified site.
-
-
+REST API: [Encrypt Extracts](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm#encrypt_extracts){:target="_blank"}
----
+**Parameters**
+Name | Description
+:--- | :---
+`site_id` | The identifier (`id`) for the site on which to encrypt all extracts.
-## Server
+**Version**
-In the Tableau REST API, the server (`https://MY-SERVER/`) is the base or core of the URI that makes up the various endpoints or methods for accessing resources on the server (views, workbooks, sites, users, data sources, etc.)
-The TSC library provides a `Server` class that represents the server. You create a server instance to sign in to the server and to call the various methods for accessing resources.
+Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+
+**Example**
+```py
+server.sites.encrypt_extracts(server.site_id)
+```
-
-### Server class
+#### sites.decrypt_extracts
```py
-Server(server_address)
+sites.decrypt_extracts(site_id)
```
-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**
+Decrypts all extracts on the specified site.
-Attribute | Description
+REST API: [Decrypt Extracts](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm#decrypt_extracts){:target="_blank"}
+
+**Parameters**
+
+Name | Description
:--- | :---
-`server_address` | Specifies the address of the Tableau Server or Tableau Cloud (for example, `https://MY-SERVER/`).
-`version` | Specifies the version of the REST API to use (for example, `'2.5'`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to `'2.3'`, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+`site_id` | The identifier (`id`) for the site on which to decrypt all extracts.
+**Version**
+Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
**Example**
```py
-import tableauserverclient as TSC
+server.sites.decrypt_extracts(server.site_id)
+```
+
+
-# create a instance of server
-server = TSC.Server('https://MY-SERVER')
+#### sites.re_encrypt_extracts
-# sign in, etc.
+```py
+sites.re_encrypt_extracts(site_id)
+```
-# change the REST API version to match the server
-server.use_server_version()
+Re-encrypts all extracts on the specified site using new encryption keys.
-# or change the REST API version to match a specific version
-# for example, 2.8
-# server.version = '2.8'
+REST API: [Reencrypt Extracts](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm#reencrypt_extracts){:target="_blank"}
-```
+**Parameters**
-#### Server.*Resources*
+Name | Description
+:--- | :---
+`site_id` | The identifier (`id`) for the site on which to re-encrypt all extracts.
-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()`
+**Version**
+Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+**Example**
-Resource | Description
- :--- | : ---
-*server*.auth | Sets authentication for sign in and sign out. See [Auth](#authentication) |
-*server*.views | Access the server views and methods. See [Views](#views)
-*server*.users | Access the user resources and methods. See [Users](#users)
-*server*.sites | Access the sites. See [Sites](#sites)
-*server*.groups | Access the groups resources and methods. See [Groups](#groups)
-*server*.jobs | Access the jobs resources and methods. See [Jobs](#jobs)
-*server*.workbooks | Access the resources and methods for workbooks. See [Workbooks](#workbooks)
-*server*.datasources | Access the resources and methods for data sources. See [Data Sources](#data-sources)
-*server*.projects | Access the resources and methods for projects. See [Projects](#projects)
-*server*.schedules | Access the resources and methods for schedules. See [Schedules](#schedules)
-*server*.subscriptions | Access the resources and methods for subscriptions. See [Subscriptions](#subscriptions)
-*server*.server_info | Access the resources and methods for server information. See [ServerInfo class](#serverinfoitem-class)
+```py
+server.sites.re_encrypt_extracts(server.site_id)
+```
-#### 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`.
+## Sort
-**Properties**
+The `Sort` class is used with request options (`RequestOptions`) where you can filter and sort on the results returned from the server.
-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.
+You can use the sort and request options to filter and sort the following endpoints:
+- Users
+- Datasources
+- Workbooks
+- Views
-**Example**
+### Sort class
```py
- import tableauserverclient as TSC
- # login, etc.
+sort(field, direction)
+```
- print(TSC.Server.PublishMode.Overwrite)
- # prints 'Overwrite'
- overwrite_true = TSC.Server.PublishMode.Overwrite
- ...
+**Attributes**
- # pass the PublishMode to the publish workbooks method
- new_workbook = server.workbooks.publish(new_workbook, args.filepath, overwrite_true)
+Name | Description
+:--- | :---
+`field` | Sets the field to sort on. The fields are defined in the `RequestOption` class.
+`direction` | The direction to sort, either ascending (`Asc`) or descending (`Desc`). The options are defined in the `RequestOptions.Direction` class.
+
+**Example**
+
+```py
+
+# 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](filter-sort).
+---
-### ServerInfoItem class
+## Subscriptions
+
+Using the TSC library, you can manage subscriptions to views or workbooks on a site. You can get information about all the subscriptions on a site, or information about a specific subscription on a site, and you can create, update, or delete subscriptions.
+
+### SubscriptionItem class
+
+The subscription resources for Tableau Server are defined in the `SubscriptionItem` class. The class corresponds to the subscription resources you can access using the Tableau Server REST API. The subscription methods are based upon the endpoints for subscriptions in the REST API and operate on the `SubscriptionItem` class.
```py
-ServerInfoItem(product_version, build_number, rest_api_version)
+SubscriptionItem(subject, schedule_id, user_id, target)
+
```
-The `ServerInfoItem` class contains the build and version information for Tableau Server. The server information is accessed with the `server_info.get()` method, which returns an instance of the `ServerInfo` class.
**Attributes**
-Name | Description
+Name | Description
:--- | :---
-`product_version` | Shows the version of the Tableau Server or Tableau Cloud (for example, 10.2.0).
-`build_number` | Shows the specific build number (for example, 10200.17.0329.1446).
-`rest_api_version` | Shows the supported REST API version number. Note that this might be different from the default value specified for the server, with the `Server.version` attribute. To take advantage of new features, you should query the server and set the `Server.version` to match the supported REST API version number.
-
+`id` | The id of the subscription on the site.
+`attach_image` | Setting this to `True` will cause the subscriber to receive mail with .png images of workbooks or views attached to it. By default, this value is set to `True`. If `attach_pdf` is set to `False`, then this value cannot be set to `False`.
+`attach_pdf` | Setting this to `True` will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. By default, this value is set to `False`.
+`message` | The text body of the subscription email message.
+`page_orientation` | The orientation of the pages produced when `attach_pdf` is `True`. If this parameter is not present the page orientation will default to `Portrait`. See chart below for a full list of values.
+`page_size_option` | The type of page produced, which determines the page dimensions when `attach_pdf` is `True`. If this parameter is not present the page type will default to `Letter`. See chart below for a full list of values.
+`schedule_id` | The id of the schedule associated with the specific subscription.
+`send_if_view_empty` | Applies to views only (see `target` attribute). If `True`, an image is sent even if the view specified in a subscription is empty. If `False`, nothing is sent if the view is empty. The default value is `True`.
+`subject`| The subject of the subscription. This is the description that you provide to identify the subscription.
+`suspended` | Setting this value to `True` stops email delivery for the specified subscription. Setting it to `False` will resume email delivery for the subscription.
+`target` | The target of the subscription, that is, the content that is subscribed to (view, workbook). The target is an instance of the `target` class. The `target` has two properties, the `id` of the workbook or view (`target.id`), and the `type` (`target.type`), which can either `view` or `workbook`. The `send_if_view_empty` attribute can only be set to `True` if the `target.type` is set to `View`.
+`user_id` | The identifier of the user (person) who receives the subscription.
-
+**Valid PDF options (applies only if `attach_pdf` is set to `True`)**
+Attribute | Valid options
+:--- | :---
+`page_orientation` | `TSC.PDFRequestOptions.Orientation.Landscape`
`TSC.PDFRequestOptions.Orientation.Portrait`
+`page_size_option` | `TSC.PDFRequestOptions.PageType.A3`
`TSC.PDFRequestOptions.PageType.A4`
`TSC.PDFRequestOptions.PageType.A5`
`TSC.PDFRequestOptions.PageType.B5`
`TSC.PDFRequestOptions.PageType.Executive`
`TSC.PDFRequestOptions.PageType.Folio`
`TSC.PDFRequestOptions.PageType.Ledger`
`TSC.PDFRequestOptions.PageType.Legal`
`TSC.PDFRequestOptions.PageType.Letter`
`TSC.PDFRequestOptions.PageType.Note`
`TSC.PDFRequestOptions.PageType.Quarto`
`TSC.PDFRequestOptions.PageType.Tabloid`
-### ServerInfo methods
-The TSC library provides a method to access the build and version information from Tableau Server.
+Source files:
+server/endpoints/subscription_item.py
+server/request_options.py
+
+
+### Subscription methods
+
+The Tableau Server Client provides several methods for interacting with subscription resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
+
+
+Source files: server/endpoints/subscriptions_endpoint.py
+
+
-#### server_info.get
+#### subscriptions.create
```py
-server_info.get()
-
+subscriptions.create(subscription_item)
```
-Retrieve the build and version information for the server.
+Creates a subscription to a view or workbook for a specific user on a specific schedule.
+When a user is subscribed to the content, Tableau Server sends the content to the user in email on the schedule that's defined on Tableau Server and specified in the `subscription_item`.
-This method makes an unauthenticated call, so no sign in or authentication token is required.
+To create a new subscription you need to first create a new `subscription_item` (from `SubscriptionItem` class).
-REST API: [Server Info](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#server_info)
+
+REST API: [Create Subscription](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_subscription)
**Parameters**
- None
-**Exceptions**
+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.
-Error | Description
-:--- | :---
-`404003 UNKNOWN_RESOURCE` | Raises an exception if the server info endpoint is not found.
-**Example**
+**Returns**
-```py
-import tableauserverclient as TSC
+Returns the new `SubscriptionItem` object.
-# create a instance of server
-server = TSC.Server('https://MY-SERVER')
-# set the version number > 2.3
-# the server_info.get() method works in 2.4 and later
-server.version = '2.5'
-s_info = server.server_info.get()
-print("\nServer info:")
-print("\tProduct version: {0}".format(s_info.product_version))
-print("\tREST API version: {0}".format(s_info.rest_api_version))
-print("\tBuild number: {0}".format(s_info.build_number))
-```
+**Example**
+```py
+# 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)
-## Sites
+# (Optional) Set other fields. Any of these can be added or removed.
+new_sub.attach_image = False
+new_sub.attach_pdf = True
+new_sub.message = "You have an alert!"
+new_sub.page_orientation = TSC.PDFRequestOptions.Orientation.Landscape
+new_sub.page_size_option = TSC.PDFRequestOptions.PageType.B4
+new_sub.send_if_view_empty = True
-Using the TSC library, you can query a site or sites on a server, or create or delete a site on the server.
+# Create the new subscription on the site you are logged in.
+new_sub = server.subscriptions.create(new_sub)
+print(new_sub.subject)
+```
-The site resources for Tableau Server and Tableau Cloud are defined in the `SiteItem` class. The class corresponds to the site resources you can access using the Tableau Server REST API. The site methods are based upon the endpoints for sites in the REST API and operate on the `SiteItem` class.
-### SiteItem class
+
+
+#### subscriptions.delete
```py
-SiteItem(name, content_url, admin_mode=None, user_quota=None, storage_quota=None,
- disable_subscriptions=False, subscribe_others_enabled=True, revision_history_enabled=False)
+subscriptions.delete(subscription_id)
```
-The `SiteItem` class contains the members or attributes for the site resources on Tableau Server or Tableau Cloud. The `SiteItem` class defines the information you can request or query from Tableau Server or Tableau Cloud. The class members correspond to the attributes of a server request or response payload.
-**Attributes**
-Attribute | Description
-:--- | :---
-`name` | The name of the site. The name of the default site is "".
-`content_url` | The path to the site.
-`admin_mode` | (Optional) For Tableau Server only. Specify `ContentAndUsers` to allow site administrators to use the server interface and **tabcmd** commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify `ContentOnly` to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.)
-`user_quota`| (Optional) Specifies the total number of users for the site. The number can't exceed the number of licenses activated for the site; and if tiered capacity attributes are set, then `user_quota` will equal the sum of the tiered capacity values, and attempting to set `user_quota` will cause an error.
-Tiered capacity attributes: `tier_explorer_capacity` `tier_creator_capacity` `tier_viewer_capacity`| (Optional) The maximum number of licenses for users with the Creator, Explorer, or Viewer role, respectively, allowed on a site.
-`storage_quota` | (Optional) Specifies the maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again.
-`disable_subscriptions` | (Optional) Specify `true` to prevent users from being able to subscribe to workbooks on the specified site. The default is `false`.
-`subscribe_others_enabled` | (Optional) Specify `false` to prevent server administrators, site administrators, and project or content owners from being able to subscribe other users to workbooks on the specified site. The default is `true`.
-`revision_history_enabled` | (Optional) Specify `true` to enable revision history for content resources (workbooks and datasources). The default is `false`.
-`revision_limit` | (Optional) Specifies the number of revisions of a content source (workbook or data source) to allow. On Tableau Server, the default is 25.
-`state` | Shows the current state of the site (`Active` or `Suspended`).
+Deletes the specified subscription from the site.
+REST API: [Delete Subscription](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_subscription)
-**Example**
-```py
+**Parameters**
-# create a new instance of a SiteItem
+Name | Description
+ :--- | : ---
+`subscription_id` | The identifier (`id`) for the subscription that you want to remove from the site.
-new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode='ContentAndUsers', user_quota=15, storage_quota=1000, disable_subscriptions=True)
-```
+**Exceptions**
-Source file: models/site_item.py
+Error | Description
+ :--- | : ---
+`Subscription ID undefined` | Raises an exception if a valid `subscription_id` is not provided.
-
-
+**Example**
-### SiteAuthConfiguration class
+```py
+# Remove a subscription from the site
-The `SiteAuthConfiguration` class contains the attributes for the authentication configuration on Tableau Cloud. This class represents the authentication configuration information returned when using the `sites.list_auth_configurations` method.
+# import tableauserverclient as TSC
+# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='SITE')
+# server = TSC.Server('https://SERVERURL')
-**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.
+ with server.auth.sign_in(tableau_auth):
+ server.subscriptions.delete('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
-**Example**
+```
+
+
-```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
+
+
-# Get authentication configurations for the current site
-auth_configs = server.sites.list_auth_configurations()
+#### subscriptions.get
-# Display configuration details
-for config in auth_configs:
- print(f"ID: {config.idp_configuration_id}")
- print(f"Name: {config.idp_configuration_name}")
- print(f"Type: {config.auth_setting}")
- print(f"Enabled: {config.enabled}")
- print(f"Provider: {config.known_provider_alias}")
+```py
+subscriptions.get(req_options=None)
```
+Returns information about the subscriptions on the specified site.
-
-
-### Site methods
+REST API: [Query Subscriptions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_subscriptions)
-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.
+**Parameters**
+Name | Description
+ :--- | : ---
+`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific subscription, you could specify the subject of the subscription or the id of the subscription.
+
+
+**Returns**
+Returns a list of `SubscriptionItem` objects and a `PaginationItem` object. Use these values to iterate through the results.
-Source file: server/endpoint/sites_endpoint.py
-#### sites.create
+#### subscriptions.get_by_id
+
```py
-sites.create(site_item)
+subscriptions.get_by_id(subscription_id)
```
-Creates a new site on the server for the specified site item object.
+Returns information about the specified subscription.
-Tableau Server only.
+REST API: [Query Subscription](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_subscription)
-REST API: [Create Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_site)
+**Parameters**
+
+Name | Description
+ :--- | : ---
+`subscription_id` | The `subscription_id` specifies the subscription to query.
-**Parameters**
+**Exceptions**
-Name | Description
-:--- | :---
-`site_item` | The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass it to the `create` method.
+Error | Description
+ :--- | : ---
+`No Subscription ID provided.` | Raises an exception if a valid `subscription_id` is not provided.
**Returns**
-Returns a new instance of `SiteItem`.
+The `SubscriptionItem`. See [SubscriptionItem class](#subscriptionitem-class)
**Example**
-```py
-import tableauserverclient as TSC
-
-# create an instance of server
-server = TSC.Server('https://MY-SERVER')
-
-# create shortcut for admin mode
-content_users=TSC.SiteItem.AdminMode.ContentAndUsers
-
-# create a new SiteItem
-new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode=content_users, user_quota=15, storage_quota=1000, disable_subscriptions=True)
+```py
+ sub1 = server.subscriptions.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
+ print(sub1.subject)
-# call the sites create method with the SiteItem
-new_site = server.sites.create(new_site)
```
+
-#### sites.get
+#### subscriptions.update
```py
-sites.get()
+subscriptions.update(subscription_item)
```
+Updates a specific subscription. To update a subscription, you must first query it from server using the `subscriptions.get()` or `subscriptions.get_by_id()` method.
-Queries all the sites on the server.
-
-
-REST API: [Query Sites](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_sites)
+REST API: [Update Subscription](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_subscription)
**Parameters**
- None.
+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 a list of all `SiteItem` objects and a `PaginationItem`. Use these values to iterate through the results.
+Returns the updated `SubscriptionItem` object.
**Example**
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
-
- # query the sites
- all_sites, pagination_item = server.sites.get()
-
- # print all the site names and ids
- for site in all_sites:
- print(site.id, site.name, site.content_url, site.state)
+# Fetch an existing subscription from server. You can also use the subscriptions.get() method
+sub = server.subscriptions.get_by_id('59cec1ec-15a0-4eb3-bc9d-056b87aa0a18')
+# Set update-able fields. Any of these can be added or removed.
+sub.subject = "Updated subject"
+sub.attach_image = True
+sub.attach_pdf = True
+sub.page_orientation = TSC.PDFRequestOptions.Orientation.Landscape
+sub.page_size_option = TSC.PDFRequestOptions.PageType.Folio
+sub.suspended = True
+sub.schedule_id = 'cf2f4465-9c4b-4536-b7cc-59994e9b7dde'
+sub.send_if_view_empty = True
+# Create the new subscription on the site you are logged in.
+sub = server.subscriptions.update(sub)
+print(new_sub.subject)
```
+---
+
+## Tables
+Using the TSC library, you can get information about the table assets on a site, update a table's description, certification, and contact, read and update its columns, and manage its permissions, data quality warnings, and tags. Table assets are external assets that Tableau Catalog discovers from the connections used by published content. The table resources are defined in the `TableItem` class, columns in the `ColumnItem` class, and the methods are based upon the table endpoints in the REST API.
-#### sites.get_by_id
+Table methods are available if your Tableau Cloud site or Tableau Server is licensed with Data Management. See the [Metadata Methods](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm){:target="_blank"} in the REST API reference.
+
+
+
+### TableItem class
```py
-sites.get_by_id(site_id)
+TableItem(name, description=None)
```
-Queries the site with the given ID.
+The `TableItem` represents a table asset on Tableau Server or Tableau Cloud. Table items are normally returned by the server from `tables.get` or `tables.get_by_id` rather than created directly.
+**Attributes**
-REST API: [Query Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_site)
+Name | Description
+:--- | :---
+`certification_note` | The certification note for the table. Settable; sent to the server by `tables.update`.
+`certified` | `True` if the table is certified. Settable (must be a boolean); sent to the server by `tables.update`.
+`columns` | The columns in the table, as an iterable of `ColumnItem` objects that fetches every page of columns from the server. You must first call `tables.populate_columns` to access this data.
+`contact_id` | The ID of the user who is the contact for the table. Settable; sent to the server by `tables.update`.
+`description` | The description of the table. Settable; sent to the server by `tables.update`. An empty string clears the description.
+`dqws` | The list of data quality warnings (`DQWItem`) for the table. You must first call `tables.populate_dqw` to access this data.
+`id` | The identifier (LUID) of the table. Read-only.
+`name` | The name of the table. Must not be empty. `tables.update` does not send the name to the server.
+`permissions` | The permissions for the table, as a list of `PermissionsRule` objects. You must first call `tables.populate_permissions` to access this data.
+`schema` | The name of the database schema that contains the table. Read-only.
-**Parameters**
+**Example**
-Name | Description
-:--- | :---
-`site_id` | The id for the site you want to query.
+```py
+import tableauserverclient as TSC
+# sign in, etc.
-**Exceptions**
+table = server.tables.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+print(table.name, table.schema, table.certified)
+```
-Error | Description
- :--- | : ---
-`Site ID undefined.` | Raises an error if an id is not specified.
+Source file: models/table_item.py
+
+
-**Returns**
+### ColumnItem class
-Returns the `SiteItem`.
+```py
+ColumnItem(name, description=None)
+```
+The `ColumnItem` represents a column in a table asset. Column items are returned by the server when you iterate over `TableItem.columns` after calling `tables.populate_columns`.
-**Example**
+**Attributes**
-```py
+Name | Description
+:--- | :---
+`description` | The description of the column. Settable; sent to the server by `tables.update_column` when it is not empty.
+`id` | The identifier (LUID) of the column. Read-only.
+`name` | The name of the column. Must not be empty. `tables.update_column` does not send the name to the server.
+`remote_type` | The data type of the column in the source database, for example `I4` or `WSTR`. Read-only. If the server response does not include a type, reading this attribute raises `AttributeError`.
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
+Source file: models/column_item.py
- 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))
+
+
-```
+### Tables methods
+
+The Tableau Server Client provides several methods for interacting with table assets. These methods correspond to endpoints in the Tableau Server REST API.
+
+Source file: server/endpoint/tables_endpoint.py
-#### sites.get_by_name
+#### tables.get
```py
-sites.get_by_name(site_name)
+tables.get(req_options=None)
```
-Queries the site with the specified name.
+Returns one page of the table assets on the site. The server returns 100 items per page by default. To iterate over every table on the site, use `TSC.Pager(server.tables)`.
+REST API: [Query Tables](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_tables){:target="_blank"}
-REST API: [Query Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_site)
+**Version**
+
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
-Name | Description
+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.
-
+`req_options` | (Optional) A `RequestOptions` object to set the page size and page number of the request.
**Returns**
-Returns the `SiteItem`.
-
+Returns a list of `TableItem` objects and a `PaginationItem` object.
**Example**
```py
+all_tables, pagination_item = server.tables.get()
+print("There are {} tables on site.".format(pagination_item.total_available))
+print([table.name for table in all_tables])
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
-
- a_site = server.sites.get_by_name('MY_SITE')
-
-
+for table in TSC.Pager(server.tables):
+ print(table.id, table.name)
```
-
-
-#### sites.update
+#### tables.get_by_id
```py
-sites.update(site_item)
+tables.get_by_id(table_id)
```
-Modifies the settings for site.
-
-
-The site item object must include the site ID and overrides all other settings.
+Returns the specified table asset.
+REST API: [Query Table](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_table){:target="_blank"}
-REST API: [Update Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_site)
+**Version**
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
-Name | Description
+Name | Description
:--- | :---
-`site_item` | The site item that you want to update. The settings specified in the site item override the current site settings.
-
+`table_id` | The identifier (`id`) of the table to return.
**Exceptions**
Error | Description
:--- | :---
-`Site item missing ID.` | The site id must be present and must match the id of the site you are updating.
-`You cannot set admin_mode to ContentOnly and also set a user quota` | To set the `user_quota`, the `AdminMode` must be set to `ContentAndUsers`
-
+`ValueError` | Raised if `table_id` is empty or `None`.
**Returns**
-Returns the updated `site_item`.
-
+Returns a `TableItem`.
**Example**
```py
-...
-
-# make some updates to an existing site_item
-site_item.name ="New name"
-
-# call update
-site_item = server.sites.update(site_item)
-
-...
+table = server.tables.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+print(table.name)
```
-
-
-
-#### sites.delete
-
+#### tables.delete
```py
-Sites.delete(site_id)
+tables.delete(table_id)
```
-Deletes the specified site.
+Permanently removes the specified table asset.
+REST API: [Remove Table](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#remove_table){:target="_blank"}
-REST API: [Delete Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_site)
+**Version**
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
-Name | Description
- :--- | : ---
-`site_id` | The id of the site that you want to delete.
-
-
+Name | Description
+:--- | :---
+`table_id` | The identifier (`id`) of the table to remove.
**Exceptions**
-Error | Description
-:--- | :---
-`Site ID Undefined.` | The site id must be present and must match the id of the site you are deleting.
+Error | Description
+:--- | :---
+`ValueError` | Raised if `table_id` is empty or `None`.
+**Returns**
+None.
**Example**
```py
-
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
-
-server.sites.delete('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')
-
+server.tables.delete('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
```
-#### sites.list_auth_configurations
+#### tables.update
```py
-sites.list_auth_configurations()
+tables.update(table_item)
```
-Lists the authentication configurations for the current site.
+Updates the description, certification, certification note, and contact of the specified table.
-REST API: [List Authentication Configurations for the current Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_site.htm#list_auth_configurations_site)
+Only the values that are set on `table_item` are sent. A value of `None` leaves the matching property unchanged on the server, and an empty string for `description` or `certification_note` clears it. The `certified`, `description`, `certification_note`, and `contact_id` values can be updated. The `name` value is not sent.
+
+REST API: [Update Table](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_table){:target="_blank"}
+
+**Version**
+
+This endpoint is available with REST API version 3.5 and up.
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`table_item` | The `TableItem` to update. It must have an `id`, so retrieve it from the server first.
+
+**Exceptions**
+
+Error | Description
+:--- | :---
+`MissingRequiredFieldError` | Raised if `table_item` does not have an `id`.
**Returns**
-Returns a list of authentication configurations for the current site.
+Returns the updated `TableItem`.
**Example**
```py
-# import tableauserverclient as TSC
-# server = TSC.Server('https://MY-SERVER')
-# sign in, etc.
-
-auth_configs = server.sites.list_auth_configurations()
-for config in auth_configs:
- print(f"IDP Configuration ID: {config.idp_configuration_id}")
- print(f"Name: {config.idp_configuration_name}")
- print(f"Type: {config.auth_setting}")
- print(f"Enabled: {config.enabled}")
+table = server.tables.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+table.description = 'One row per order line'
+table.certified = True
+table = server.tables.update(table)
```
-#### sites.get_by_content_url
+#### tables.populate_columns
```py
-sites.get_by_content_url(content_url)
+tables.populate_columns(table_item, req_options=None)
```
-Returns the site with the specified content URL.
+Populates the columns of the specified table. After calling this method, `table_item.columns` returns an iterable that requests every page of columns from the server each time you iterate over it.
-REST API: [Query Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_site.htm#query_site){:target="_blank"}
+REST API: [Query Columns in a Table](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_columns){:target="_blank"}
+
+**Version**
+
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`content_url` | The `content_url` for the site to query. This is the `contentUrl` value in the REST API and corresponds to the portion of the URL after `/site/` (for example, `"MarketingTeam"`). Use an empty string for the default site.
+`table_item` | The `TableItem` to populate with columns.
+`req_options` | (Optional) A `RequestOptions` object sent with each page request, for example to set the page size.
-**Returns**
+**Exceptions**
-Returns a `SiteItem`.
+Error | Description
+:--- | :---
+`MissingRequiredFieldError` | Raised if `table_item` does not have an `id`.
-**Version**
+**Returns**
-Version 2.0 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+None. Columns are available through `table_item.columns`.
**Example**
```py
-site = server.sites.get_by_content_url('MarketingTeam')
-print(site.id, site.name)
+table = server.tables.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+server.tables.populate_columns(table)
+for column in table.columns:
+ print(column.id, column.name, column.description)
```
-#### sites.encrypt_extracts
+#### tables.update_column
```py
-sites.encrypt_extracts(site_id)
+tables.update_column(table_item, column_item)
```
-Encrypts all extracts on the specified site.
+Updates the description of a column in the specified table. Only the `description` is sent, and only when it is not empty.
-REST API: [Encrypt Extracts](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm#encrypt_extracts){:target="_blank"}
+REST API: [Update Column](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_column){:target="_blank"}
+
+**Version**
+
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`site_id` | The identifier (`id`) for the site on which to encrypt all extracts.
+`table_item` | The `TableItem` that contains the column.
+`column_item` | The `ColumnItem` to update, with the new `description` set.
-**Version**
+**Returns**
-Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+Returns the updated `ColumnItem`.
**Example**
```py
-server.sites.encrypt_extracts(server.site_id)
+server.tables.populate_columns(table)
+column = next(iter(table.columns))
+column.description = 'Order date in UTC'
+column = server.tables.update_column(table, column)
```
-#### sites.decrypt_extracts
+#### tables.populate_permissions
```py
-sites.decrypt_extracts(site_id)
+tables.populate_permissions(item)
```
-Decrypts all extracts on the specified site.
+Populates the permissions for the specified table. After calling this method, the permissions are available through `item.permissions`.
-REST API: [Decrypt Extracts](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm#decrypt_extracts){:target="_blank"}
+REST API: [List Table Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_table_perms){:target="_blank"}
+
+**Version**
+
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`site_id` | The identifier (`id`) for the site on which to decrypt all extracts.
+`item` | The `TableItem` to populate with permissions.
-**Version**
+**Exceptions**
-Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+Error | Description
+:--- | :---
+`MissingRequiredFieldError` | Raised if `item` does not have an `id`.
+
+**Returns**
+
+None. Permissions are populated on `item.permissions`.
**Example**
```py
-server.sites.decrypt_extracts(server.site_id)
+table = server.tables.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
+server.tables.populate_permissions(table)
+for rule in table.permissions:
+ print(rule.grantee.tag_name, rule.grantee.id, rule.capabilities)
```
-#### sites.re_encrypt_extracts
+#### tables.update_permissions
```py
-sites.re_encrypt_extracts(site_id)
+tables.update_permissions(item, rules)
```
-Re-encrypts all extracts on the specified site using new encryption keys.
+Adds permissions to the specified table.
+
+REST API: [Add Table Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#add_table_perms){:target="_blank"}
-REST API: [Reencrypt Extracts](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm#reencrypt_extracts){:target="_blank"}
+**Version**
+
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
Name | Description
:--- | :---
-`site_id` | The identifier (`id`) for the site on which to re-encrypt all extracts.
+`item` | The `TableItem` to add permissions to.
+`rules` | A list of `PermissionsRule` objects to add.
-**Version**
+**Returns**
-Version 3.5 and later. See [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).
+Returns the list of `PermissionsRule` objects in the server response.
**Example**
```py
-server.sites.re_encrypt_extracts(server.site_id)
+rule = TSC.PermissionsRule(
+ grantee=TSC.GroupItem.as_reference('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d'),
+ capabilities={TSC.Permission.Capability.Read: TSC.Permission.Mode.Allow},
+)
+server.tables.update_permissions(table, [rule])
```
----
-
+#### tables.delete_permission
-## Sort
-
-The `Sort` class is used with request options (`RequestOptions`) where you can filter and sort on the results returned from the server.
+```py
+tables.delete_permission(item, rules)
+```
-You can use the sort and request options to filter and sort the following endpoints:
+Removes permissions from the specified table. For each rule, every capability in `rule.capabilities` is removed for `rule.grantee` with a separate request.
-- Users
-- Datasources
-- Workbooks
-- Views
+REST API: [Delete Table Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_table_perms){:target="_blank"}
-### Sort class
+**Version**
-```py
-sort(field, direction)
-```
+This endpoint is available with REST API version 3.5 and up.
+**Parameters**
+Name | Description
+:--- | :---
+`item` | The `TableItem` to remove permissions from.
+`rules` | A list of `PermissionsRule` objects to remove. A single `PermissionsRule` is also accepted.
-**Attributes**
+**Returns**
-Name | Description
-:--- | :---
-`field` | Sets the field to sort on. The fields are defined in the `RequestOption` class.
-`direction` | The direction to sort, either ascending (`Asc`) or descending (`Desc`). The options are defined in the `RequestOptions.Direction` class.
+None.
**Example**
```py
-
-# 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)
+server.tables.populate_permissions(table)
+server.tables.delete_permission(table, table.permissions[:1])
```
-For information about using the `Sort` class, see [Filter and Sort](filter-sort).
-
----
-
-## Subscriptions
+#### tables.populate_dqw
-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.
+```py
+tables.populate_dqw(item)
+```
-### SubscriptionItem class
+Populates the data quality warnings for the specified table. After calling this method, the warnings are available through `item.dqws`.
-The subscription resources for Tableau Server are defined in the `SubscriptionItem` class. The class corresponds to the subscription resources you can access using the Tableau Server REST API. The subscription methods are based upon the endpoints for subscriptions in the REST API and operate on the `SubscriptionItem` class.
+REST API: [Query Data Quality Warning by Content](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_dqws){:target="_blank"}
-```py
-SubscriptionItem(subject, schedule_id, user_id, target)
+**Version**
-```
+This endpoint is available with REST API version 3.5 and up.
-**Attributes**
+**Parameters**
Name | Description
:--- | :---
-`id` | The id of the subscription on the site.
-`attach_image` | Setting this to `True` will cause the subscriber to receive mail with .png images of workbooks or views attached to it. By default, this value is set to `True`. If `attach_pdf` is set to `False`, then this value cannot be set to `False`.
-`attach_pdf` | Setting this to `True` will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. By default, this value is set to `False`.
-`message` | The text body of the subscription email message.
-`page_orientation` | The orientation of the pages produced when `attach_pdf` is `True`. If this parameter is not present the page orientation will default to `Portrait`. See chart below for a full list of values.
-`page_size_option` | The type of page produced, which determines the page dimensions when `attach_pdf` is `True`. If this parameter is not present the page type will default to `Letter`. See chart below for a full list of values.
-`schedule_id` | The id of the schedule associated with the specific subscription.
-`send_if_view_empty` | Applies to views only (see `target` attribute). If `True`, an image is sent even if the view specified in a subscription is empty. If `False`, nothing is sent if the view is empty. The default value is `True`.
-`subject`| The subject of the subscription. This is the description that you provide to identify the subscription.
-`suspended` | Setting this value to `True` stops email delivery for the specified subscription. Setting it to `False` will resume email delivery for the subscription.
-`target` | The target of the subscription, that is, the content that is subscribed to (view, workbook). The target is an instance of the `target` class. The `target` has two properties, the `id` of the workbook or view (`target.id`), and the `type` (`target.type`), which can either `view` or `workbook`. The `send_if_view_empty` attribute can only be set to `True` if the `target.type` is set to `View`.
-`user_id` | The identifier of the user (person) who receives the subscription.
+`item` | The `TableItem` to populate with data quality warnings.
-
-**Valid PDF options (applies only if `attach_pdf` is set to `True`)**
+**Exceptions**
-Attribute | Valid options
+Error | Description
:--- | :---
-`page_orientation` | `TSC.PDFRequestOptions.Orientation.Landscape`
`TSC.PDFRequestOptions.Orientation.Portrait`
-`page_size_option` | `TSC.PDFRequestOptions.PageType.A3`
`TSC.PDFRequestOptions.PageType.A4`
`TSC.PDFRequestOptions.PageType.A5`
`TSC.PDFRequestOptions.PageType.B5`
`TSC.PDFRequestOptions.PageType.Executive`
`TSC.PDFRequestOptions.PageType.Folio`
`TSC.PDFRequestOptions.PageType.Ledger`
`TSC.PDFRequestOptions.PageType.Legal`
`TSC.PDFRequestOptions.PageType.Letter`
`TSC.PDFRequestOptions.PageType.Note`
`TSC.PDFRequestOptions.PageType.Quarto`
`TSC.PDFRequestOptions.PageType.Tabloid`
-
-
-Source files:
-server/endpoints/subscription_item.py
-server/request_options.py
+`MissingRequiredFieldError` | Raised if `item` does not have an `id`.
+**Returns**
-### Subscription methods
-
-The Tableau Server Client provides several methods for interacting with subscription resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
-
+None. Warnings are populated on `item.dqws`.
+**Example**
-Source files: server/endpoints/subscriptions_endpoint.py
+```py
+server.tables.populate_dqw(table)
+for dqw in table.dqws:
+ print(dqw.warning_type, dqw.message)
+```
-#### subscriptions.create
+#### tables.add_dqw
```py
-subscriptions.create(subscription_item)
+tables.add_dqw(item, warning)
```
-Creates a subscription to a view or workbook for a specific user on a specific schedule.
-When a user is subscribed to the content, Tableau Server sends the content to the user in email on the schedule that's defined on Tableau Server and specified in the `subscription_item`.
-To create a new subscription you need to first create a new `subscription_item` (from `SubscriptionItem` class).
+Adds a data quality warning to the specified table.
+REST API: [Add Data Quality Warning](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#add_dqw){:target="_blank"}
-REST API: [Create Subscription](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_subscription)
+**Version**
-**Parameters**
+This endpoint is available with REST API version 3.5 and up.
-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.
+**Parameters**
+Name | Description
+:--- | :---
+`item` | The `TableItem` to add the warning to.
+`warning` | The `DQWItem` to add.
**Returns**
-Returns the new `SubscriptionItem` object.
-
-
-
+Returns the list of `DQWItem` objects in the server response.
**Example**
```py
-# Create the target (content) of the subscription with its ID and type.
-# ID can be obtained by calling workbooks.get() or views.get().
-target = TSC.Target('c7a9327e-1cda-4504-b026-ddb43b976d1d', 'workbook')
-
-# Store the schedule ID and user ID.
-# IDs can be obtained by calling schedules.get() and users.get().
-schedule_id = 'b60b4efd-a6f7-4599-beb3-cb677e7abac1'
-user_id = '28ce5884-ed38-49a9-aa10-8f5fbd59bbf6'
-
-# Create the new SubscriptionItem object with variables from above.
-new_sub = TSC.SubscriptionItem('My Subscription', schedule_id, user_id, target)
-
-# (Optional) Set other fields. Any of these can be added or removed.
-new_sub.attach_image = False
-new_sub.attach_pdf = True
-new_sub.message = "You have an alert!"
-new_sub.page_orientation = TSC.PDFRequestOptions.Orientation.Landscape
-new_sub.page_size_option = TSC.PDFRequestOptions.PageType.B4
-new_sub.send_if_view_empty = True
-
-# Create the new subscription on the site you are logged in.
-new_sub = server.subscriptions.create(new_sub)
-print(new_sub.subject)
+warning = TSC.DQWItem(warning_type=TSC.DQWItem.WarningType.DEPRECATED, message='Use the orders_v2 table instead')
+server.tables.add_dqw(table, warning)
```
-
-
-
-#### subscriptions.delete
+#### tables.update_dqw
```py
-subscriptions.delete(subscription_id)
+tables.update_dqw(item, warning)
```
+Updates the data quality warning on the specified table.
+The request is sent as a `PUT` to `/dataQualityWarnings/table/{table-id}`, using the ID of `item`. The `id` of `warning` is not used. The REST API reference documents Update Data Quality Warning as a `PUT` to `/dataQualityWarnings/{warning-id}`, so check the result against your server.
-Deletes the specified subscription from the site.
+REST API: [Update Data Quality Warning](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_dqw){:target="_blank"}
-REST API: [Delete Subscription](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_subscription)
+**Version**
+This endpoint is available with REST API version 3.5 and up.
**Parameters**
-Name | Description
- :--- | : ---
-`subscription_id` | The identifier (`id`) for the subscription that you want to remove from the site.
-
-
-**Exceptions**
+Name | Description
+:--- | :---
+`item` | The `TableItem` whose warning to update.
+`warning` | The `DQWItem` with the updated values.
-Error | Description
- :--- | : ---
-`Subscription ID undefined` | Raises an exception if a valid `subscription_id` is not provided.
+**Returns**
+Returns the list of `DQWItem` objects in the server response.
**Example**
```py
-# Remove a subscription from the site
-
-# import tableauserverclient as TSC
-# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='SITE')
-# server = TSC.Server('https://SERVERURL')
-
-
- with server.auth.sign_in(tableau_auth):
- server.subscriptions.delete('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
-
+server.tables.populate_dqw(table)
+warning = table.dqws[0]
+warning.severe = True
+server.tables.update_dqw(table, warning)
```
-
-
-#### subscriptions.get
+#### tables.delete_dqw
```py
-subscriptions.get(req_options=None)
+tables.delete_dqw(item)
```
-Returns information about the subscriptions on the specified site.
+Removes the data quality warnings from the specified table.
-REST API: [Query Subscriptions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_subscriptions)
+REST API: [Delete Data Quality Warning by Content](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_dqws){:target="_blank"}
-**Parameters**
+**Version**
-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.
+This endpoint is available with REST API version 3.5 and up.
+
+**Parameters**
+Name | Description
+:--- | :---
+`item` | The `TableItem` to remove the warnings from.
**Returns**
-Returns a list of `SubscriptionItem` objects and a `PaginationItem` object. Use these values to iterate through the results.
+None.
+
+**Example**
+
+```py
+server.tables.delete_dqw(table)
+```
-#### subscriptions.get_by_id
-
+#### tables.add_tags
```py
-subscriptions.get_by_id(subscription_id)
+tables.add_tags(item, tags)
```
-Returns information about the specified subscription.
-
-REST API: [Query Subscription](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_subscription)
+Adds one or more tags to the specified table.
+REST API: [Add Tags to Table](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#add_tags_table){:target="_blank"}
-**Parameters**
+**Version**
-Name | Description
- :--- | : ---
-`subscription_id` | The `subscription_id` specifies the subscription to query.
+This endpoint is available with REST API version 3.9 and up.
+**Parameters**
+Name | Description
+:--- | :---
+`item` | The `TableItem` or table ID to add tags to.
+`tags` | A single tag string or an iterable of tag strings to add.
**Exceptions**
-Error | Description
- :--- | : ---
-`No Subscription ID provided.` | Raises an exception if a valid `subscription_id` is not provided.
-
+Error | Description
+:--- | :---
+`ValueError` | Raised if `item` is not a table ID string and has no `id`.
**Returns**
-The `SubscriptionItem`. See [SubscriptionItem class](#subscriptionitem-class)
-
+Returns a `set[str]` of the tags in the server response.
**Example**
```py
- sub1 = server.subscriptions.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d')
- print(sub1.subject)
-
+server.tables.add_tags(table, ['finance', 'quarterly'])
```
-#### subscriptions.update
+#### tables.delete_tags
```py
-subscriptions.update(subscription_item)
+tables.delete_tags(item, tags)
```
-Updates a specific subscription. To update a subscription, you must first query it from server using the `subscriptions.get()` or `subscriptions.get_by_id()` method.
+Removes one or more tags from the specified table. Each tag is removed with a separate request.
-REST API: [Update Subscription](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_subscription)
+REST API: Delete Tag from Table, in the [Metadata Methods](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm){:target="_blank"} reference.
+
+**Version**
+
+This endpoint is available with REST API version 3.9 and up.
**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.
+Name | Description
+:--- | :---
+`item` | The `TableItem` or table ID to remove tags from.
+`tags` | A single tag string or an iterable of tag strings to remove.
+**Exceptions**
-**Returns**
+Error | Description
+:--- | :---
+`ValueError` | Raised if `item` is not a table ID string and has no `id`.
-Returns the updated `SubscriptionItem` object.
+**Returns**
+None.
**Example**
```py
-# Fetch an existing subscription from server. You can also use the subscriptions.get() method
-sub = server.subscriptions.get_by_id('59cec1ec-15a0-4eb3-bc9d-056b87aa0a18')
+server.tables.delete_tags(table, 'quarterly')
+```
-# Set update-able fields. Any of these can be added or removed.
-sub.subject = "Updated subject"
-sub.attach_image = True
-sub.attach_pdf = True
-sub.page_orientation = TSC.PDFRequestOptions.Orientation.Landscape
-sub.page_size_option = TSC.PDFRequestOptions.PageType.Folio
-sub.suspended = True
-sub.schedule_id = 'cf2f4465-9c4b-4536-b7cc-59994e9b7dde'
-sub.send_if_view_empty = True
+
+
-# Create the new subscription on the site you are logged in.
-sub = server.subscriptions.update(sub)
-print(new_sub.subject)
+#### tables.update_tags
+
+```py
+tables.update_tags(item)
```
+Not supported for tables. `TableItem` does not track a tag set, so this method always raises `NotImplementedError`. Use `tables.add_tags` and `tables.delete_tags` instead.
+
----
-
## Tasks
Using the TSC library, you can get information about all the tasks on a site and you can remove tasks. To create new tasks see [Schedules](#schedules).
diff --git a/docs/samples.md b/docs/samples.md
index fc36622ba..b9d1f3f1d 100644
--- a/docs/samples.md
+++ b/docs/samples.md
@@ -46,6 +46,7 @@ The following list describes the samples available in the repository:
* `create_project.py` Creates a project in a site.
* `create_schedules.py` Creates schedules for extract refreshes and subscriptions.
* `create_user.py` Creates a user on a site.
+* `explore_databases_tables.py` Queries databases, shows one database's details, lists its tables, then populates and lists the columns of one table. Optionally shows database and table permissions.
* `explore_datasource.py` Queries datasources, selects a datasource, populates connections for the datasource, then updates the datasource.
* `explore_favorites.py` Queries favorites and optionally add or delete favorites.
* `explore_site.py` Interacts with sites (create, delete, and so on).