feat: enable bulk adding users

Author: jorwoods

tableauserverclient/server/endpoint/users_endpoint.py

@@ -1,14 +1,19 @@
 import copy
+import csv
+import io
+import itertools
 import logging
-from typing import List, Optional, Tuple
+from pathlib import Path
+import re
+from typing import List, Iterable, Optional, Tuple, Union
 
 from tableauserverclient.server.query import QuerySet
 
 from .endpoint import QuerysetEndpoint, api
 from .exceptions import MissingRequiredFieldError, ServerResponseError
 from tableauserverclient.server import RequestFactory, RequestOptions
-from tableauserverclient.models import UserItem, WorkbookItem, PaginationItem, GroupItem
-from ..pager import Pager
+from tableauserverclient.models import UserItem, WorkbookItem, PaginationItem, GroupItem, JobItem
+from tableauserverclient.server.pager import Pager
 
 from tableauserverclient.helpers.logging import logger
 
@@ -97,8 +102,25 @@ def add_all(self, users: List[UserItem]):
 
     # helping the user by parsing a file they could have used to add users through the UI
     # line format: Username [required], password, display name, license, admin, publish
+    @api(version="3.15")
+    def bulk_add(self, users: Iterable[UserItem]) -> JobItem:
+        """
+        line format: Username [required], password, display name, license, admin, publish
+        """
+        url = f"{self.baseurl}/import"
+        # Allow for iterators to be passed into the function
+        csv_users, xml_users = itertools.tee(users, 2)
+        csv_content = create_users_csv(csv_users)
+
+        xml_request, content_type = RequestFactory.User.import_from_csv_req(csv_content, xml_users)
+        server_response = self.post_request(url, xml_request, content_type)
+        return JobItem.from_response(server_response.content, self.parent_srv.namespace).pop()
+
     @api(version="2.0")
     def create_from_file(self, filepath: str) -> Tuple[List[UserItem], List[Tuple[UserItem, ServerResponseError]]]:
+        import warnings
+
+        warnings.warn("This method is deprecated, use bulk_add instead", DeprecationWarning)
         created = []
         failed = []
         if not filepath.find("csv"):
@@ -159,16 +181,6 @@ def groups_for_user_pager():
 
         user_item._set_groups(groups_for_user_pager)
 
-    def _get_groups_for_user(
-        self, user_item: UserItem, req_options: Optional[RequestOptions] = None
-    ) -> Tuple[List[GroupItem], PaginationItem]:
-        url = "{0}/{1}/groups".format(self.baseurl, user_item.id)
-        server_response = self.get_request(url, req_options)
-        logger.info("Populated groups for user (ID: {0})".format(user_item.id))
-        group_item = GroupItem.from_response(server_response.content, self.parent_srv.namespace)
-        pagination_item = PaginationItem.from_response(server_response.content, self.parent_srv.namespace)
-        return group_item, pagination_item
-
     def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[UserItem]:
         """
         Queries the Tableau Server for items using the specified filters. Page
@@ -205,3 +217,53 @@ def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySe
         """
 
         return super().filter(*invalid, page_size=page_size, **kwargs)
+
+    def _get_groups_for_user(
+        self, user_item: UserItem, req_options: Optional[RequestOptions] = None
+    ) -> Tuple[List[GroupItem], PaginationItem]:
+        url = "{0}/{1}/groups".format(self.baseurl, user_item.id)
+        server_response = self.get_request(url, req_options)
+        logger.info("Populated groups for user (ID: {0})".format(user_item.id))
+        group_item = GroupItem.from_response(server_response.content, self.parent_srv.namespace)
+        pagination_item = PaginationItem.from_response(server_response.content, self.parent_srv.namespace)
+        return group_item, pagination_item
+
+def create_users_csv(users: Iterable[UserItem], identity_pool=None) -> bytes:
+    """
+    Create a CSV byte string from an Iterable of UserItem objects
+    """
+    if identity_pool is not None:
+        raise NotImplementedError("Identity pool is not supported in this version")
+    with io.StringIO() as output:
+        writer = csv.writer(output, quoting=csv.QUOTE_MINIMAL)
+        for user in users:
+            site_role = user.site_role or "Unlicensed"
+            if site_role == "ServerAdministrator":
+                license = "Creator"
+                admin_level = "System"
+            elif site_role.startswith("SiteAdministrator"):
+                admin_level = "Site"
+                license = site_role.replace("SiteAdministrator", "")
+            else:
+                license = site_role
+                admin_level = ""
+
+            if any(x in site_role for x in ("Creator", "Admin", "Publish")):
+                publish = 1
+            else:
+                publish = 0
+
+            writer.writerow(
+                (
+                    user.name,
+                    getattr(user, "password", ""),
+                    user.fullname,
+                    license,
+                    admin_level,
+                    publish,
+                    user.email,
+                )
+            )
+        output.seek(0)
+        result = output.read().encode("utf-8")
+    return result

tableauserverclient/server/request_factory.py

@@ -905,6 +905,21 @@ def add_req(self, user_item: UserItem) -> bytes:
             user_element.attrib["authSetting"] = user_item.auth_setting
         return ET.tostring(xml_request)
 
+    def import_from_csv_req(self, csv_content: bytes, users: Iterable[UserItem]):
+        xml_request = ET.Element("tsRequest")
+        for user in users:
+            if user.name is None:
+                raise ValueError("User name must be populated.")
+            user_element = ET.SubElement(xml_request, "user")
+            user_element.attrib["name"] = user.name
+            user_element.attrib["authSetting"] = user.auth_setting or "ServerDefault"
+
+        parts = {
+            "tableau_user_import": ("tsc_users_file.csv", csv_content, "file"),
+            "request_payload": ("", ET.tostring(xml_request), "text/xml"),
+        }
+        return _add_multipart(parts)
+
 
 class WorkbookRequest(object):
     def _generate_xml(

test/assets/users_bulk_add_job.xml

@@ -0,0 +1,4 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api https://help.tableau.com/samples/en-us/rest_api/ts-api_3_20.xsd">
+    <job id="16a3479e-0ff9-4685-a0e4-1533b3c2eb96" mode="Asynchronous" type="UserImport" progress="0" createdAt="2024-06-27T03:21:02Z" finishCode="1"/>
+</tsResponse>

test/test_user.py

@@ -1,16 +1,20 @@
+import csv
 import io
 import os
+from pathlib import Path
 import unittest
 from typing import List
 from unittest.mock import MagicMock
 
+from defusedxml.ElementTree import fromstring
 import requests_mock
 
 import tableauserverclient as TSC
 from tableauserverclient.datetime_helpers import format_datetime
 
-TEST_ASSET_DIR = os.path.join(os.path.dirname(__file__), "assets")
+TEST_ASSET_DIR = Path(__file__).resolve().parent / "assets"
 
+BULK_ADD_XML = TEST_ASSET_DIR / "users_bulk_add_job.xml"
 GET_XML = os.path.join(TEST_ASSET_DIR, "user_get.xml")
 GET_EMPTY_XML = os.path.join(TEST_ASSET_DIR, "user_get_empty.xml")
 GET_BY_ID_XML = os.path.join(TEST_ASSET_DIR, "user_get_by_id.xml")
@@ -236,3 +240,82 @@ def test_get_users_from_file(self):
             users, failures = self.server.users.create_from_file(USERS)
         assert users[0].name == "Cassie", users
         assert failures == []
+
+    def test_bulk_add(self):
+        self.server.version = "3.15"
+        users = [
+            TSC.UserItem(
+                "test",
+                "Viewer",
+            )
+        ]
+        with requests_mock.mock() as m:
+            m.post(f"{self.server.users.baseurl}/import", text=BULK_ADD_XML.read_text())
+
+            job = self.server.users.bulk_add(users)
+
+            assert m.last_request.method == "POST"
+            assert m.last_request.url == f"{self.server.users.baseurl}/import"
+
+            body = m.last_request.body.replace(b"\r\n", b"\n")
+            assert body.startswith(b"--")  # Check if it's a multipart request
+            boundary = body.split(b"\n")[0].strip()
+
+            # Body starts and ends with a boundary string. Split the body into
+            # segments and ignore the empty sections at the start and end.
+            segments = [seg for s in body.split(boundary) if (seg := s.strip()) not in [b"", b"--"]]
+            assert len(segments) == 2  # Check if there are two segments
+
+            # Check if the first segment is the csv file and the second segment is the xml
+            assert b'Content-Disposition: form-data; name="tableau_user_import"' in segments[0]
+            assert b'Content-Disposition: form-data; name="request_payload"' in segments[1]
+            assert b"Content-Type: file" in segments[0]
+            assert b"Content-Type: text/xml" in segments[1]
+
+            xml_string = segments[1].split(b"\n\n")[1].strip()
+            xml = fromstring(xml_string)
+            xml_users = xml.findall(".//user", namespaces={})
+            assert len(xml_users) == len(users)
+
+            for user, xml_user in zip(users, xml_users):
+                assert user.name == xml_user.get("name")
+                assert xml_user.get("authSetting") == (user.auth_setting or "ServerDefault")
+
+            license_map = {
+                "Viewer": "Viewer",
+                "Explorer": "Explorer",
+                "ExplorerCanPublish": "Explorer",
+                "Creator": "Creator",
+                "SiteAdministratorExplorer": "Explorer",
+                "SiteAdministratorCreator": "Creator",
+                "ServerAdministrator": "Creator",
+                "Unlicensed": "Unlicensed",
+            }
+            publish_map = {
+                "Unlicensed": 0,
+                "Viewer": 0,
+                "Explorer": 0,
+                "Creator": 1,
+                "ExplorerCanPublish": 1,
+                "SiteAdministratorExplorer": 1,
+                "SiteAdministratorCreator": 1,
+                "ServerAdministrator": 1,
+            }
+            admin_map = {
+                "SiteAdministratorExplorer": "Site",
+                "SiteAdministratorCreator": "Site",
+                "ServerAdministrator": "System",
+            }
+
+            csv_columns = ["name", "password", "fullname", "license", "admin", "publish", "email"]
+            csv_file = io.StringIO(segments[0].split(b"\n\n")[1].decode("utf-8"))
+            csv_reader = csv.reader(csv_file)
+            for user, row in zip(users, csv_reader):
+                site_role = user.site_role or "Unlicensed"
+                csv_user = dict(zip(csv_columns, row))
+                assert user.name == csv_user["name"]
+                assert (user.fullname or "") == csv_user["fullname"]
+                assert (user.email or "") == csv_user["email"]
+                assert license_map[site_role] == csv_user["license"]
+                assert admin_map.get(site_role, "") == csv_user["admin"]
+                assert publish_map[site_role] == int(csv_user["publish"])