diff --git a/docs/api-ref.md b/docs/api-ref.md index 589cd2b5..7804d9cd 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -5361,6 +5361,120 @@ An updated `UserItem`. See [UserItem class](#useritem-class)

+#### users.add_all + +```py +users.add_all(users) +``` + +**DEPRECATED** + +Adds a list of users to the site. Unlike `bulk_add`, this method adds users one at a time and collects successes and failures. + +**Parameters** + +Name | Description +:--- | :--- +`users` | A list of `UserItem` objects to add to the site. + +**Returns** + +Returns a tuple of two lists: `(created, failed)`. The `created` list contains the successfully added `UserItem` objects. The `failed` list contains the `UserItem` objects that could not be added. + +**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 +users_to_add = [TSC.UserItem('user1'), TSC.UserItem('user2')] +created, failed = server.users.add_all(users_to_add) +print("Added {} users, {} failed.".format(len(created), len(failed))) +``` + +
+
+ +#### users.create_from_file + +```py +users.create_from_file(filepath) +``` + +**DEPRECATED** + +Adds users from a CSV file to the site. The CSV file format matches the format used in the Tableau Server UI for bulk user import. + +The CSV file should have the following column format (header row optional): +`Username, Password, Display Name, License Level, Admin Level, Publishing Access` + +**Parameters** + +Name | Description +:--- | :--- +`filepath` | The path to a CSV file containing user information to import. + +**Exceptions** + +Error | Description +:--- | :--- +`ValueError` | Raises an exception if the file path does not point to a CSV file. + +**Returns** + +Returns a tuple of two lists: `(created, failed)`. The `created` list contains successfully added `UserItem` objects. The `failed` list contains tuples of `(UserItem, ServerResponseError)` for users that could not be added. + +**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 +created, failed = server.users.create_from_file('/path/to/users.csv') +print("Imported {} users. {} failed.".format(len(created), len(failed))) +for user, error in failed: + print("Failed to import {}: {}".format(user.name, error)) +``` + +
+
+ +#### users.filter + +```py +users.filter(**kwargs) +``` + +Returns a list of users 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 +:--- | :--- +`domain_name` | `eq`, `in` +`friendly_name` | `eq`, `in` +`is_local` | `eq` +`last_login` | `eq`, `gt`, `gte`, `lt`, `lte` +`luid` | `eq`, `in` +`name` | `eq`, `cieq`, `in` +`site_role` | `eq`, `in` + +**Returns** + +Returns a `QuerySet` of `UserItem` objects. + +**Example** + +```py +viewers = server.users.filter(site_role='Viewer') +for user in viewers: + print(user.name) +``` + +
+
---