pyxecm 2.0.2__py3-none-any.whl → 2.0.4__py3-none-any.whl

pyxecm/otcs.py

@@ -27,10 +27,12 @@ import threading
 import time
 import urllib.parse
 import zipfile
+from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 from functools import cache
 from http import HTTPStatus
 from importlib.metadata import version
+from queue import Empty, LifoQueue, Queue
 
 import requests
 import websockets
@@ -148,6 +150,38 @@ class OTCS:
     ITEM_TYPE_WORKFLOW_MAP = 128
     ITEM_TYPE_WORKFLOW_STATUS = 190
 
+    CONTAINER_ITEM_TYPES = [
+        ITEM_TYPE_FOLDER,
+        ITEM_TYPE_BUSINESS_WORKSPACE,
+        ITEM_TYPE_COMPOUND_DOCUMENT,
+        ITEM_TYPE_CLASSIFICATION,
+        VOLUME_TYPE_ENTERPRISE_WORKSPACE,
+        VOLUME_TYPE_CLASSIFICATION_VOLUME,
+        VOLUME_TYPE_CONTENT_SERVER_DOCUMENT_TEMPLATES,
+    ]
+
+    PERMISSION_TYPES = [
+        "see",
+        "see_contents",
+        "modify",
+        "edit_attributes",
+        "add_items",
+        "reserve",
+        "add_major_version",
+        "delete_versions",
+        "delete",
+        "edit_permissions",
+    ]
+    PERMISSION_ASSIGNEE_TYPES = [
+        "owner",
+        "group",
+        "public",
+        "custom",
+    ]
+
+    # The maximum length of an item name in OTCS:
+    MAX_ITEM_NAME_LENGTH = 248
+
     _config: dict
     _otcs_ticket = None
     _otds_ticket = None
@@ -165,6 +199,42 @@ class OTCS:
     )  # only 1 thread should handle the re-authentication
     _session_lock = threading.Lock()
 
+    @classmethod
+    def cleanse_item_name(cls, item_name: str, max_length: int | None = None) -> str:
+        """Cleanse the given name of an OTCS item.
+
+        Control for forbidden characters and check the item name length.
+
+        Args:
+            item_name (str):
+                The item name to cleanse.
+            max_length (int, optional):
+                A specific maximum length for custom cases.
+                If not provided we will use the default OTCS.MAX_ITEM_NAME_LENGTH.
+
+        Returns:
+            str:
+                The cleansed item name.
+
+        """
+
+        # If no custom max length is given we use the default:
+        if max_length is None:
+            max_length = OTCS.MAX_ITEM_NAME_LENGTH
+
+        # Item names for sure are not allowed to have ":":
+        item_name = item_name.replace(":", "")
+        # Item names for sure should not have leading or trailing spaces:
+        item_name = item_name.strip()
+        # Truncate the item name to 248 characters which is the maximum
+        # allowed length in Content Server
+        if len(item_name) > max_length:
+            item_name = item_name[:max_length]
+
+        return item_name
+
+    # end method definition
+
     @classmethod
     def date_is_newer(cls, date_old: str, date_new: str) -> bool:
         """Compare two dates, typically create or modification dates.
@@ -443,6 +513,7 @@ class OTCS:
         self._semaphore = threading.BoundedSemaphore(value=thread_number)
         self._last_session_renewal = 0
         self._use_numeric_category_identifier = use_numeric_category_identifier
+        self._executor = ThreadPoolExecutor(max_workers=thread_number)
 
     # end method definition
 
@@ -716,6 +787,21 @@ class OTCS:
 
     # end method definition
 
+    def clear_data(self) -> Data:
+        """Reset the data object to an empty data frame.
+
+        Returns:
+            Data:
+                Newly initialized data object.
+
+        """
+
+        self._data = Data(logger=self.logger)
+
+        return self._data
+
+    # end method definition
+
     def request_form_header(self) -> dict:
         """Deliver the request header used for the CRUD REST API calls.
 
@@ -858,6 +944,9 @@ class OTCS:
                 # a cookie that is in process of being renewed
                 # by another thread:
                 with self._session_lock:
+                    if not self.cookie():
+                        self.logger.error("Cannot call -> %s - user is not authenticatd!", url)
+                        return None
                     # IMPORTANT: this needs to be a copy - dicts are mutable and
                     # we need to preserve the old value to detect in reauthenticate()
                     # if the cookie has been renewed already or not:
@@ -1436,7 +1525,7 @@ class OTCS:
         property_name: str = "properties",
         data_name: str = "data",
     ) -> list | None:
-        """Read an item value from the REST API response.
+        """Read all values with a given key from the REST API response.
 
         This method handles the most common response structures delivered by the
         V2 REST API of Extended ECM. For more details, refer to the documentation at
@@ -1530,6 +1619,44 @@ class OTCS:
 
     # end method definition
 
+    def get_result_values_iterator(
+        self,
+        response: dict,
+        property_name: str = "properties",
+        data_name: str = "data",
+    ) -> iter:
+        """Get an iterator object that can be used to traverse through OTCS responses.
+
+        This method handles the most common response structures delivered by the
+        V2 REST API of Extended ECM. For more details, refer to the documentation at
+        developer.opentext.com.
+
+        Args:
+            response (dict):
+                REST API response object.
+            property_name (str, optional):
+                Name of the sub-dictionary holding the actual values.
+                Defaults to "properties".
+            data_name (str, optional):
+                Name of the sub-dictionary holding the data.
+                Defaults to "data".
+
+        Returns:
+            list | None:
+                Value list of the item with the given key, or None if no value is found.
+
+        """
+
+        # First do some sanity checks:
+        if not response:
+            return
+        if "results" not in response:
+            return
+
+        yield from (item[data_name][property_name] for item in response["results"])
+
+    # end method definition
+
     def is_configured(self) -> bool:
         """Check if the Content Server pod is configured to receive requests.
 
@@ -1671,11 +1798,8 @@ class OTCS:
                 "Requesting OTCS ticket with existing OTDS ticket; calling -> %s",
                 request_url,
             )
-            request_header = {
-                "Content-Type": "application/x-www-form-urlencoded",
-                "Accept": "application/json",
-                "OTDSTicket": self._otds_ticket,
-            }
+            # Add the OTDS ticket to the request headers:
+            request_header = REQUEST_FORM_HEADERS | {"OTDSTicket": self._otds_ticket}
 
             try:
                 response = requests.get(
@@ -1923,7 +2047,7 @@ class OTCS:
         """
 
         request_url = self.config()["serverInfoUrl"]
-        request_header = self.request_form_header()  # self.cookie()
+        request_header = self.request_form_header()
 
         self.logger.debug(
             "Retrieve Content Server information; calling -> %s",
@@ -2018,57 +2142,141 @@ class OTCS:
 
     # end method definition
 
-    @cache
-    def get_user(self, name: str, show_error: bool = False) -> dict | None:
-        """Look up an Content Server user based on the login name.
+    def get_users(
+        self,
+        where_type: int = 0,
+        where_name: str | None = None,
+        where_first_name: str | None = None,
+        where_last_name: str | None = None,
+        where_business_email: str | None = None,
+        query_string: str | None = None,
+        sort: str | None = None,
+        limit: int = 20,
+        page: int = 1,
+        show_error: bool = False,
+    ) -> dict | None:
+        """Get a Content Server users based on different criterias.
+
+        The criterias can be combined.
 
         Args:
-            name (str):
+            where_type (int, optional):
+                Type ID of user:
+                0 - Regular User
+                17 - Service User
+                Defaults to 0 -> (Regular User)
+            where_name (str | None = None):
                 Name of the user (login).
+            where_first_name (str | None = None):
+                First name of the user.
+            where_last_name (str | None = None):
+                Last name of the user.
+            where_business_email (str | None = None):
+                Business email address of the user.
+            query_string (str | None = None):
+                Filters the results, returning the users with the specified query string
+                in any of the following fields: log-in name, first name, last name, email address,
+                and groups with the specified query string in the group name.
+                NOTE: query cannot be used together with any combination of: where_name,
+                where_first_name, where_last_name, where_business_email.
+                The query value will be used to perform a search within the log-in name,
+                first name, last name and email address properties for users and group name
+                for groups to see if that value is contained within any of those properties.
+                This differs from the user search that is performed in Classic UI where it
+                searches for a specific property that begins with the value provided by the user.
+            sort (str | None = None):
+                Order by named column (Using prefixes such as sort=asc_name or sort=desc_name).
+                Format can be sort = id, sort = name, sort = first_name, sort = last_name,
+                sort = group_id, sort = mailaddress. If the prefix of asc or desc is not used
+                then asc will be assumed.
+                Default is None.
+            limit (int, optional):
+                The maximum number of results per page (internal default is 10). OTCS does
+                not allow values > 20 so this method adjusts values > 20 to 20.
+            page (int, optional):
+                The page number to retrieve.
             show_error (bool, optional):
                 If True, treat as an error if the user is not found. Defaults to False.
 
         Returns:
             dict | None:
-                User information as a dictionary, or None if the user is not found.
+                User information as a dictionary, or None if the user could not be found
+                (e.g., because it doesn't exist).
 
         Example:
             ```json
             {
                 'collection': {
-                    'paging': {...},
-                    'sorting': {...}
+                    'paging': {
+                        'limit': 10,
+                        'page': 1,
+                        'page_total': 1,
+                        'range_max': 1,
+                        'range_min': 1,
+                        'total_count': 1
+                    },
+                    'sorting': {
+                        'sort': [
+                            {
+                                'key': 'sort',
+                                'value': 'asc_id'
+                            }
+                        ]
+                    }
                 },
                 'links': {
-                    'data': {...}
+                    'data': {
+                        'self': {
+                            'body': '',
+                            'content_type': '',
+                            'href': '/api/v2/members?where_first_name=Peter',
+                            'method': 'GET',
+                            'name': ''
+                        }
+                    }
                 },
                 'results': [
                     {
                         'data': {
-                            'birth_date': None,
-                            'business_email': 'pramos@M365x61936377.onmicrosoft.com',
-                            'business_fax': None,
-                            'business_phone': None,
-                            'cell_phone': None,
-                            'deleted': False,
-                            'display_language': None,
-                            'first_name': 'Peter',
-                            'gender': None,
-                            'group_id': 8006,
-                            'home_address_1': None,
-                            'home_address_2': None,
-                            'home_fax': None,
-                            'home_phone': None,
-                            'id': 8123,
-                            'initials': None,
-                            'last_name': 'Ramos',
-                            'middle_name': None,
-                            'name': 'pramos',
-                            'name_formatted': 'Peter Ramos',
-                            'photo_id': 13981,
-                            'photo_url': 'api/v1/members/8123/photo?v=13981.1',
-                            'type': 0,
-                            'type_name': 'User'
+                            'properties': {
+                                'birth_date': None,
+                                'business_email': 'pramos@M365x61936377.onmicrosoft.com',
+                                'business_fax': None,
+                                'business_phone': None,
+                                'cell_phone': None,
+                                'deleted': False,
+                                'display_language': None,
+                                'first_name': 'Peter',
+                                'gender': None,
+                                'group_id': 8006,
+                                'home_address_1': None,
+                                'home_address_2': None,
+                                'home_fax': None,
+                                'home_phone': None,
+                                'id': 8123,
+                                'initials': None,
+                                'last_name': 'Ramos',
+                                'middle_name': None,
+                                'name': 'pramos',
+                                'name_formatted': 'Peter Ramos',
+                                'office_location': None,
+                                'pager': None,
+                                'personal_email': None,
+                                'photo_id': 13981,
+                                'photo_url': 'api/v1/members/8123/photo?v=13981.1',
+                                'privilege_content_manager': False,
+                                'privilege_grant_discovery': False,
+                                'privilege_login': True,
+                                'privilege_modify_groups': False,
+                                'privilege_modify_users': False,
+                                'privilege_public_access': True,
+                                'privilege_system_admin_rights': False,
+                                'privilege_user_admin_rights': False,
+                                'time_zone': -1,
+                                'title': 'Maintenance Planner',
+                                'type': 0,
+                                'type_name': 'User'
+                            }
                         }
                     }
                 ]
@@ -2081,17 +2289,45 @@ class OTCS:
 
         """
 
-        # Add query parameters (these are NOT passed via JSon body!)
-        # type = 0 ==> User
-        query = {"where_type": 0, "where_name": name}
+        # Add query parameters (embedded in the URL)
+        # Using type = 0 for OTCS groups or type = 17 for service user:
+        query = {}
+        filter_string = " type -> 'service user'" if where_type == 17 else ""
+        query["where_type"] = where_type
+        if where_name:
+            query["where_name"] = where_name
+            filter_string += " login name -> '{}'".format(where_name) if where_name else ""
+        if where_first_name:
+            query["where_first_name"] = where_first_name
+            filter_string += " first name -> '{}'".format(where_first_name) if where_first_name else ""
+        if where_last_name:
+            query["where_last_name"] = where_last_name
+            filter_string += " last name -> '{}'".format(where_last_name) if where_last_name else ""
+        if where_business_email:
+            query["where_business_email"] = where_business_email
+            filter_string += " business email -> '{}'".format(where_business_email) if where_business_email else ""
+        if query_string:
+            query["query"] = query_string
+            filter_string += " query -> '{}'".format(query_string) if where_business_email else ""
+        if sort:
+            query["sort"] = sort
+        if limit:
+            if limit > 20:
+                self.logger.warning(
+                    "Page limit for user query cannot be larger than 20. Adjusting from %d to 20.", limit
+                )
+                limit = 20
+            query["limit"] = limit
+        if page:
+            query["page"] = page
         encoded_query = urllib.parse.urlencode(query=query, doseq=True)
         request_url = self.config()["membersUrlv2"] + "?{}".format(encoded_query)
 
         request_header = self.request_form_header()
 
         self.logger.debug(
-            "Get user with login name -> '%s'; calling -> %s",
-            name,
+            "Get users%s; calling -> %s",
+            " with{}".format(filter_string) if filter_string else "",
             request_url,
         )
 
@@ -2100,97 +2336,159 @@ class OTCS:
             method="GET",
             headers=request_header,
             timeout=None,
-            failure_message="Failed to get user with login -> '{}'".format(name),
-            warning_message="Couldn't find user with login -> '{}'".format(name),
+            failure_message="Failed to get users{}".format(" with{}".format(filter_string) if filter_string else ""),
+            warning_message="Couldn't find users{}".format(" with{}".format(filter_string) if filter_string else ""),
             show_error=show_error,
         )
 
     # end method definition
 
-    def add_user(
+    def get_users_iterator(
         self,
-        name: str,
-        password: str,
-        first_name: str,
-        last_name: str,
-        email: str,
-        title: str,
-        base_group: int,
-        privileges: list | None = None,
-        user_type: int = 0,
-    ) -> dict | None:
-        """Add Content Server user.
+        where_type: int = 0,
+        where_name: str | None = None,
+        where_first_name: str | None = None,
+        where_last_name: str | None = None,
+        where_business_email: str | None = None,
+        query_string: str | None = None,
+        sort: str | None = None,
+        limit: int = 20,
+    ) -> iter:
+        """Get an iterator object that can be used to traverse OTCS users.
+
+        Filters can be applied that are given by the "where" and "query" parameters.
+
+        Using a generator avoids loading a large users into memory at once.
+        Instead you can iterate over the potential large list of users.
+
+        Example usage:
+            ```python
+            users = otcs_object.get_users_iterator(where_type=0, limit=10)
+            for user in users:
+                logger.info(
+                    "Traversing user -> '%s' (%s)",
+                    otcs_object.get_result_value(response=user, key="name"),
+                    otcs_object.get_result_value(response=user, key="id"),
+                )
+            ```
 
         Args:
-            name (str): login name of the user
-            password (str): password of the user
-            first_name (str): first name of the user
-            last_name (str): last name of the user
-            email (str): email address of the user
-            title (str): title of the user
-            base_group (int): base group id of the user (e.g. department)
-            privileges (list, optional):
-                Possible values are Login, Public Access, Content Manager,
-                Modify Users, Modify Groups, User Admin Rights,
-                Grant Discovery, System Admin Rights
-            user_type (int, optional): id of user_type 0-User, 17-ServiceUser, ...
+            where_type (int, optional):
+                Type ID of user:
+                0 - Regular User
+                17 - Service User
+                Defaults to 0 -> (Regular User)
+            where_name (str | None = None):
+                Name of the user (login).
+            where_first_name (str | None = None):
+                First name of the user.
+            where_last_name (str | None = None):
+                Last name of the user.
+            where_business_email (str | None = None):
+                Business email address of the user.
+            query_string (str | None = None):
+                Filters the results, returning the users with the specified query string
+                in any of the following fields: log-in name, first name, last name, email address,
+                and groups with the specified query string in the group name.
+                NOTE: query cannot be used together with any combination of: where_name,
+                where_first_name, where_last_name, where_business_email.
+                The query value will be used to perform a search within the log-in name,
+                first name, last name and email address properties for users and group name
+                for groups to see if that value is contained within any of those properties.
+                This differs from the user search that is performed in Classic UI where it
+                searches for a specific property that begins with the value provided by the user.
+            sort (str | None = None):
+                Order by named column (Using prefixes such as sort=asc_name or sort=desc_name).
+                Format can be sort = id, sort = name, sort = first_name, sort = last_name,
+                sort = group_id, sort = mailaddress. If the prefix of asc or desc is not used
+                then asc will be assumed.
+                Default is None.
+            limit (int, optional):
+                The maximum number of results per page (internal default is 10). OTCS does
+                not allow values > 20 so this method adjusts values > 20 to 20.
 
         Returns:
-            dict | None:
-                User information or None if the user couldn't be created
-                (e.g. because it exisits already).
+            iter:
+                A generator yielding one user per iteration.
+                If the REST API fails, returns no value.
 
         """
 
-        if privileges is None:
-            privileges = ["Login", "Public Access"]
+        # First we probe how many members we have:
+        response = self.get_users(
+            where_type=where_type,
+            where_name=where_name,
+            where_first_name=where_first_name,
+            where_last_name=where_last_name,
+            where_business_email=where_business_email,
+            query_string=query_string,
+            limit=1,
+            page=1,
+        )
+        if not response or "results" not in response:
+            # Don't return None! Plain return is what we need for iterators.
+            # Natural Termination: If the generator does not yield, it behaves
+            # like an empty iterable when used in a loop or converted to a list:
+            return
 
-        user_post_body = {
-            "type": user_type,
-            "name": name,
-            "password": password,
-            "first_name": first_name,
-            "last_name": last_name,
-            "business_email": email,
-            "title": title,
-            "group_id": base_group,
-            "privilege_login": ("Login" in privileges),
-            "privilege_public_access": ("Public Access" in privileges),
-            "privilege_content_manager": ("Content Manager" in privileges),
-            "privilege_modify_users": ("Modify Users" in privileges),
-            "privilege_modify_groups": ("Modify Groups" in privileges),
-            "privilege_user_admin_rights": ("User Admin Rights" in privileges),
-            "privilege_grant_discovery": ("Grant Discovery" in privileges),
-            "privilege_system_admin_rights": ("System Admin Rights" in privileges),
-        }
+        number_of_users = response["collection"]["paging"]["total_count"]
+        if not number_of_users:
+            self.logger.warning(
+                "No users found! Cannot iterate over users.",
+            )
+            # Don't return None! Plain return is what we need for iterators.
+            # Natural Termination: If the generator does not yield, it behaves
+            # like an empty iterable when used in a loop or converted to a list:
+            return
 
-        request_url = self.config()["membersUrlv2"]
-        request_header = self.request_form_header()
+        # If the group has many members we need to go through all pages
+        # Adding page_size - 1 ensures that any remainder from the division is
+        # accounted for, effectively rounding up. Integer division (//) performs floor division,
+        # giving the desired number of pages:
+        total_pages = (number_of_users + limit - 1) // limit
 
-        self.logger.debug("Add user -> '%s'; calling -> %s", name, request_url)
+        for page in range(1, total_pages + 1):
+            # Get the next page of sub node items:
+            response = self.get_users(
+                where_type=where_type,
+                where_name=where_name,
+                where_first_name=where_first_name,
+                where_last_name=where_last_name,
+                where_business_email=where_business_email,
+                query_string=query_string,
+                sort=sort,
+                limit=limit,
+                page=page,
+            )
+            if not response or not response.get("results", None):
+                self.logger.warning(
+                    "Failed to retrieve users (page -> %d)",
+                    page,
+                )
+                return
 
-        # Clear user cache
-        self.get_user.cache_clear()
+            # Yield nodes one at a time:
+            yield from response["results"]
 
-        return self.do_request(
-            url=request_url,
-            method="POST",
-            headers=request_header,
-            data=user_post_body,
-            timeout=None,
-            failure_message="Failed to add user -> '{}'".format(name),
-        )
+        # end for page in range(1, total_pages + 1)
 
     # end method definition
 
-    def search_user(self, value: str, field: str = "where_name") -> dict | None:
-        """Find a user based on search criteria.
+    @cache
+    def get_user(self, name: str, user_type: int = 0, show_error: bool = False) -> dict | None:
+        """Get a Content Server user based on the login name and type.
 
         Args:
-            value (str):
-                Field value to search for.
-            field (str):
-                User field to search with (e.g. "where_name", "where_first_name", "where_last_name").
+            name (str):
+                Name of the user (login).
+            user_type (int, optional):
+                Type ID of user:
+                0 - Regular User
+                17 - Service User
+                Defaults to 0 -> (Regular User)
+
+            show_error (bool, optional):
+                If True, treat as an error if the user is not found. Defaults to False.
 
         Returns:
             dict | None:
@@ -2201,11 +2499,162 @@ class OTCS:
             ```json
             {
                 'collection': {
-                    'paging': {...},
-                    'sorting': {...}
+                    'paging': {
+                        'limit': 10,
+                        'page': 1,
+                        'page_total': 1,
+                        'range_max': 1,
+                        'range_min': 1,
+                        'total_count': 1
+                    },
+                    'sorting': {
+                        'sort': [
+                            {
+                                'key': 'sort',
+                                'value': 'asc_id'
+                            }
+                        ]
+                    }
                 },
                 'links': {
-                    'data': {...}
+                    'data': {
+                        'self': {
+                            'body': '',
+                            'content_type': '',
+                            'href': '/api/v2/members?where_first_name=Peter',
+                            'method': 'GET',
+                            'name': ''
+                        }
+                    }
+                },
+                'results': [
+                    {
+                        'data': {
+                            'properties': {
+                                'birth_date': None,
+                                'business_email': 'pramos@M365x61936377.onmicrosoft.com',
+                                'business_fax': None,
+                                'business_phone': None,
+                                'cell_phone': None,
+                                'deleted': False,
+                                'display_language': None,
+                                'first_name': 'Peter',
+                                'gender': None,
+                                'group_id': 8006,
+                                'home_address_1': None,
+                                'home_address_2': None,
+                                'home_fax': None,
+                                'home_phone': None,
+                                'id': 8123,
+                                'initials': None,
+                                'last_name': 'Ramos',
+                                'middle_name': None,
+                                'name': 'pramos',
+                                'name_formatted': 'Peter Ramos',
+                                'office_location': None,
+                                'pager': None,
+                                'personal_email': None,
+                                'photo_id': 13981,
+                                'photo_url': 'api/v1/members/8123/photo?v=13981.1',
+                                'privilege_content_manager': False,
+                                'privilege_grant_discovery': False,
+                                'privilege_login': True,
+                                'privilege_modify_groups': False,
+                                'privilege_modify_users': False,
+                                'privilege_public_access': True,
+                                'privilege_system_admin_rights': False,
+                                'privilege_user_admin_rights': False,
+                                'time_zone': -1,
+                                'title': 'Maintenance Planner',
+                                'type': 0,
+                                'type_name': 'User'
+                            }
+                        }
+                    }
+                ]
+            }
+            ```
+
+            To access the (login) name of the first user found, use
+            `["results"][0]["data"]["properties"]["name"]`.
+            Alternatively, use the method `get_result_value(response, "name", 0)`.
+
+        """
+
+        # Add query parameters (embedded in the URL)
+        # Using type = 0 for OTCS groups or type = 17 for service user:
+        query = {"where_type": user_type, "where_name": name}
+        encoded_query = urllib.parse.urlencode(query=query, doseq=True)
+        request_url = self.config()["membersUrlv2"] + "?{}".format(encoded_query)
+
+        request_header = self.request_form_header()
+
+        self.logger.debug(
+            "Get user with login name -> '%s'%s; calling -> %s",
+            name,
+            ", type -> 'service user'" if user_type == 17 else "",
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            failure_message="Failed to get user with login -> '{}' and type -> {}".format(name, user_type),
+            warning_message="Couldn't find user with login -> '{}' and type -> {}".format(name, user_type),
+            show_error=show_error,
+        )
+
+    # end method definition
+
+    def search_user(self, value: str, field: str = "where_name") -> dict | None:
+        """Find a user based on search criteria.
+
+        Args:
+            value (str):
+                Field value to search for.
+            field (str):
+                User field to search with (e.g. "where_type", "where_name",
+                "where_first_name", "where_last_name", "where_business_email", "query").
+
+        Returns:
+            dict | None:
+                User information as a dictionary, or None if the user could not be found
+                (e.g., because it doesn't exist).
+
+        Example:
+            ```json
+            {
+                'collection': {
+                    'paging': {
+                        'limit': 10,
+                        'links': {'data': {...}},
+                        'page': 1,
+                        'page_total': 2,
+                        'range_max': 10,
+                        'range_min': 1,
+                        'total_count': 11
+                    },
+                    'sorting': {
+                        'sort': [
+                            {
+                                'key': 'sort',
+                                'value': 'asc_id'
+                            }
+                        ]
+                    }
+                },
+                'links': {
+                    'data': {
+                        'self': {
+                            'body': '',
+                            'content_type': '',
+                            'href': '/api/v2/members?where_first_name=Peter',
+                            'method': 'GET',
+                            'name': ''
+                        }
+                    }
                 },
                 'results': [
                     {
@@ -2231,7 +2680,23 @@ class OTCS:
                                 'middle_name': None,
                                 'name': 'dfoxhoven',
                                 'name_formatted': 'Deke Foxhoven',
-                                ...
+                                'office_location': None,
+                                'pager': None,
+                                'personal_email': None,
+                                'photo_id': 17467,
+                                'photo_url': 'api/v1/members/8123/photo?v=17467.1',
+                                'privilege_content_manager': False,
+                                'privilege_grant_discovery': False,
+                                'privilege_login': True,
+                                'privilege_modify_groups': False,
+                                'privilege_modify_users': False,
+                                'privilege_public_access': True,
+                                'privilege_system_admin_rights': False,
+                                'privilege_user_admin_rights': False,
+                                'time_zone': -1,
+                                'title': 'Contract Manager',
+                                'type': 0,
+                                'type_name': 'User'
                             }
                         }
                     }
@@ -2264,13 +2729,100 @@ class OTCS:
 
     # end method definition
 
+    def add_user(
+        self,
+        name: str,
+        password: str,
+        first_name: str,
+        last_name: str,
+        email: str,
+        title: str,
+        base_group: int,
+        privileges: list | None = None,
+        user_type: int = 0,
+    ) -> dict | None:
+        """Add Content Server user.
+
+        Args:
+            name (str):
+                The login name of the user.
+            password (str):
+                The password of the user.
+            first_name (str):
+                The first name of the user.
+            last_name (str):
+                The last name of the user.
+            email (str):
+                The email address of the user.
+            title (str):
+                The title of the user.
+            base_group (int):
+                The base group id of the user (e.g. department)
+            privileges (list, optional):
+                Possible values are Login, Public Access, Content Manager,
+                Modify Users, Modify Groups, User Admin Rights,
+                Grant Discovery, System Admin Rights
+            user_type (int, optional):
+                The ID of the user type. 0 = regular user, 17 = service user.
+
+        Returns:
+            dict | None:
+                User information or None if the user couldn't be created
+                (e.g. because it exisits already).
+
+        """
+
+        if privileges is None:
+            privileges = ["Login", "Public Access"]
+
+        user_post_body = {
+            "type": user_type,
+            "name": name,
+            "password": password,
+            "first_name": first_name,
+            "last_name": last_name,
+            "business_email": email,
+            "title": title,
+            "group_id": base_group,
+            "privilege_login": ("Login" in privileges),
+            "privilege_public_access": ("Public Access" in privileges),
+            "privilege_content_manager": ("Content Manager" in privileges),
+            "privilege_modify_users": ("Modify Users" in privileges),
+            "privilege_modify_groups": ("Modify Groups" in privileges),
+            "privilege_user_admin_rights": ("User Admin Rights" in privileges),
+            "privilege_grant_discovery": ("Grant Discovery" in privileges),
+            "privilege_system_admin_rights": ("System Admin Rights" in privileges),
+        }
+
+        request_url = self.config()["membersUrlv2"]
+        request_header = self.request_form_header()
+
+        self.logger.debug("Add user -> '%s'; calling -> %s", name, request_url)
+
+        # Clear user cache
+        self.get_user.cache_clear()
+
+        return self.do_request(
+            url=request_url,
+            method="POST",
+            headers=request_header,
+            data=user_post_body,
+            timeout=None,
+            failure_message="Failed to add user -> '{}'".format(name),
+        )
+
+    # end method definition
+
     def update_user(self, user_id: int, field: str, value: str) -> dict | None:
         """Update a defined field for a user.
 
         Args:
-            user_id (int): ID of the user
-            value (str): field value
-            field (str): user field
+            user_id (int):
+                The ID of the user to update.
+            field (str):
+                The user data field to update.
+            value (str):
+                The new value for user data field.
 
         Returns:
             dict | None:
@@ -2656,30 +3208,252 @@ class OTCS:
 
         """
 
-        favorite_tab_post_body = {"name": tab_name, "order": str(order)}
+        favorite_tab_post_body = {"name": tab_name, "order": str(order)}
+
+        request_url = self.config()["favoritesUrl"] + "/tabs"
+        request_header = self.request_form_header()
+
+        self.logger.debug(
+            "Adding favorite tab -> %s; calling -> %s",
+            tab_name,
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="POST",
+            headers=request_header,
+            data=favorite_tab_post_body,
+            timeout=None,
+            failure_message="Failed to add favorite tab -> {}".format(tab_name),
+        )
+
+    # end method definition
+
+    def get_groups(
+        self,
+        where_name: str | None = None,
+        sort: str | None = None,
+        limit: int = 20,
+        page: int = 1,
+        show_error: bool = False,
+    ) -> dict | None:
+        """Get a list of Content Server groups.
+
+        Args:
+            where_name (str | None = None):
+                The name of the group to look up.
+            sort (str | None = None):
+                Order by named column (Using prefixes such as sort=asc_name or sort=desc_name).
+                Format can be sort = id, sort = name, sort = group_id.
+                If the prefix of asc or desc is not used then asc will be assumed.
+                Default is None.
+            limit (int, optional):
+                The maximum number of results per page (internal default is 10). OTCS does
+                not allow values > 20 so this method adjusts values > 20 to 20.
+            page (int, optional):
+                The page number to retrieve.
+            show_error (bool, optional):
+                If True, treats the absence of the group as an error. Defaults to False.
+
+        Returns:
+            dict | None:
+                Group information as a dictionary, or None if the group is not found.
+
+        Example:
+            ```json
+                {
+                    'collection': {
+                        'paging': {
+                            'limit': 10,
+                            'page': 1,
+                            'page_total': 1,
+                            'range_max': 1,
+                            'range_min': 1,
+                            'total_count': 1
+                        },
+                        'sorting': {
+                            'sort': [
+                                {
+                                    'key': 'sort',
+                                    'value': 'asc_id'
+                                }
+                            ]
+                        }
+                    },
+                    'links': {
+                        'data': {
+                            'self': {
+                                'body': '',
+                                'content_type': '',
+                                'href': '/api/v2/members?where_name=Procurement&where_type=1',
+                                'method': 'GET',
+                                'name': ''
+                            }
+                        }
+                    },
+                    'results': [
+                        {
+                            'data': {
+                                'properties': {
+                                    'deleted': False,
+                                    'id': 17649,
+                                    'initials': 'P',
+                                    'leader_id': None,
+                                    'name': 'Procurement',
+                                    'name_formatted': 'Procurement',
+                                    'type': 1,
+                                    'type_name': 'Group'
+                                }
+                            }
+                        }
+                    ]
+                }
+            ```
+
+            To access the ID of the first group found, use ["results"][0]["data"]["properties"]["id"].
+            Or use the method get_result_value(response, key="id")
+
+        """
+
+        # Add query parameters (embedded in the URL)
+        # Using type = 1 for OTCS groups:
+        query = {"where_type": 1}
+        if where_name:
+            query["where_name"] = where_name
+        if sort:
+            query["sort"] = sort
+        if limit:
+            if limit > 20:
+                self.logger.warning(
+                    "Page limit for group query cannot be larger than 20. Adjusting from %d to 20.", limit
+                )
+                limit = 20
+            query["limit"] = limit
+        if page:
+            query["page"] = page
+        encoded_query = urllib.parse.urlencode(query=query, doseq=True)
+        request_url = self.config()["membersUrlv2"] + "?{}".format(encoded_query)
+
+        request_header = self.request_form_header()
+
+        self.logger.debug(
+            "Get groups%s; calling -> %s",
+            " with name -> '{}'".format(where_name) if where_name else "",
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            failure_message="Failed to get groups{}".format(
+                " with name -> '{}'".format(where_name) if where_name else ""
+            ),
+            warning_message="Groups{} do not yet exist!".format(
+                " with name -> '{}'".format(where_name) if where_name else ""
+            ),
+            show_error=show_error,
+        )
+
+    # end method definition
+
+    def get_groups_iterator(
+        self,
+        where_name: str | None = None,
+        sort: str | None = None,
+        limit: int = 20,
+    ) -> iter:
+        """Get an iterator object that can be used to traverse OTCS groups.
+
+        Filters can be applied that are given by the "where" and "query" parameters.
+
+        Using a generator avoids loading a large number of groups into memory at once.
+        Instead you can iterate over the potential large list of groups.
+
+        Example usage:
+            ```python
+            groups = otcs_object.get_groups_iterator(limit=10)
+            for group in groups:
+                logger.info(
+                    "Traversing group -> '%s' (%s)",
+                    otcs_object.get_result_value(response=group, key="name"),
+                    otcs_object.get_result_value(response=group, key="id"),
+                )
+            ```
+
+        Args:
+            where_name (str | None = None):
+                Name of the user (login).
+            sort (str | None = None):
+                Order by named column (Using prefixes such as sort=asc_name or sort=desc_name ).
+                Format can be sort = id, sort = name, sort = group_id.
+                If the prefix of asc or desc is not used then asc will be assumed.
+                Default is None.
+            limit (int, optional):
+                The maximum number of results per page (internal default is 10). OTCS does
+                not allow values > 20 so this method adjusts values > 20 to 20.
+
+        Returns:
+            iter:
+                A generator yielding one group per iteration.
+                If the REST API fails, returns no value.
+
+        """
+
+        # First we probe how many members we have:
+        response = self.get_groups(
+            where_name=where_name,
+            limit=1,
+            page=1,
+        )
+        if not response or "results" not in response:
+            # Don't return None! Plain return is what we need for iterators.
+            # Natural Termination: If the generator does not yield, it behaves
+            # like an empty iterable when used in a loop or converted to a list:
+            return
+
+        number_of_users = response["collection"]["paging"]["total_count"]
+        if not number_of_users:
+            self.logger.warning(
+                "No groups found! Cannot iterate over groups.",
+            )
+            # Don't return None! Plain return is what we need for iterators.
+            # Natural Termination: If the generator does not yield, it behaves
+            # like an empty iterable when used in a loop or converted to a list:
+            return
+
+        # If the group has many members we need to go through all pages
+        # Adding page_size - 1 ensures that any remainder from the division is
+        # accounted for, effectively rounding up. Integer division (//) performs floor division,
+        # giving the desired number of pages:
+        total_pages = (number_of_users + limit - 1) // limit
 
-        request_url = self.config()["favoritesUrl"] + "/tabs"
-        request_header = self.request_form_header()
+        for page in range(1, total_pages + 1):
+            # Get the next page of sub node items:
+            response = self.get_groups(
+                where_name=where_name,
+                sort=sort,
+                limit=limit,
+                page=page,
+            )
+            if not response or not response.get("results", None):
+                self.logger.warning(
+                    "Failed to retrieve groups (page -> %d)",
+                    page,
+                )
+                return
 
-        self.logger.debug(
-            "Adding favorite tab -> %s; calling -> %s",
-            tab_name,
-            request_url,
-        )
+            # Yield nodes one at a time:
+            yield from response["results"]
 
-        return self.do_request(
-            url=request_url,
-            method="POST",
-            headers=request_header,
-            data=favorite_tab_post_body,
-            timeout=None,
-            failure_message="Failed to add favorite tab -> {}".format(tab_name),
-        )
+        # end for page in range(1, total_pages + 1)
 
     # end method definition
 
     def get_group(self, name: str, show_error: bool = False) -> dict | None:
-        """Look up a Content Server group.
+        """Get the Content Server group with a given name.
 
         Args:
             name (str):
@@ -2690,23 +3464,65 @@ class OTCS:
         Returns:
             dict | None:
                 Group information as a dictionary, or None if the group is not found.
-                The returned information has the following structure:
+
+        Example:
+            ```json
                 {
-                    "data": [
+                    'collection': {
+                        'paging': {
+                            'limit': 10,
+                            'page': 1,
+                            'page_total': 1,
+                            'range_max': 1,
+                            'range_min': 1,
+                            'total_count': 1
+                        },
+                        'sorting': {
+                            'sort': [
+                                {
+                                    'key': 'sort',
+                                    'value': 'asc_id'
+                                }
+                            ]
+                        }
+                    },
+                    'links': {
+                        'data': {
+                            'self': {
+                                'body': '',
+                                'content_type': '',
+                                'href': '/api/v2/members?where_name=Procurement&where_type=1',
+                                'method': 'GET',
+                                'name': ''
+                            }
+                        }
+                    },
+                    'results': [
                         {
-                            "id": 0,
-                            "name": "string",
-                            ...
+                            'data': {
+                                'properties': {
+                                    'deleted': False,
+                                    'id': 17649,
+                                    'initials': 'P',
+                                    'leader_id': None,
+                                    'name': 'Procurement',
+                                    'name_formatted': 'Procurement',
+                                    'type': 1,
+                                    'type_name': 'Group'
+                                }
+                            }
                         }
                     ]
                 }
+            ```
 
-                To access the ID of the first group found, use ["data"][0]["id"].
+            To access the ID of the first group found, use ["results"][0]["data"]["properties"]["id"].
+            Or use the method get_result_value(response, key="id")
 
         """
 
-        # Add query parameters (these are NOT passed via JSon body!)
-        # type = 1 ==> Group
+        # Add query parameters (embedded in the URL)
+        # Using type = 1 for OTCS groups:
         query = {"where_type": 1, "where_name": name}
         encoded_query = urllib.parse.urlencode(query=query, doseq=True)
         request_url = self.config()["membersUrlv2"] + "?{}".format(encoded_query)
@@ -2804,10 +3620,6 @@ class OTCS:
 
         query = {}
         query["where_type"] = str(member_type)
-        if limit:
-            query["limit"] = limit
-        if page:
-            query["page"] = page
         if where_name:
             query["where_name"] = where_name
         if where_first_name:
@@ -2816,12 +3628,13 @@ class OTCS:
             query["where_last_name"] = where_last_name
         if where_business_email:
             query["where_business_email"] = where_business_email
-
+        if limit:
+            query["limit"] = limit
+        if page:
+            query["page"] = page
         encoded_query = urllib.parse.urlencode(query=query, doseq=True)
-
-        # default limit is 25 which may not be enough for groups with many members
-        # where_type = 1 makes sure we just get groups and not users
         request_url = self.config()["membersUrlv2"] + "/" + str(group) + "/members?{}".format(encoded_query)
+
         request_header = self.request_form_header()
 
         self.logger.debug(
@@ -2856,8 +3669,8 @@ class OTCS:
 
         Filters can be applied that are given by the "where" parameters.
 
-        Using a generator avoids loading a large number of nodes into memory at once.
-        Instead you can iterate over the potential large list of related workspaces.
+        Using a generator avoids loading a large number of group members into memory at once.
+        Instead you can iterate over the potential large list of group members.
 
         Example usage:
             ```python
@@ -3669,7 +4482,8 @@ class OTCS:
         """Get a node based on the workspace ID (= node ID) and path (list of folder names).
 
         Args:
-            workspace_id (int): node ID of the workspace
+            workspace_id (int):
+                The node ID of the workspace.
             path (list):
                 A list of container items (top down).
                 The last item is name of to be retrieved item.
@@ -3871,8 +4685,10 @@ class OTCS:
         """Get a node based on the nickname.
 
         Args:
-            nickname (str): The nickname of the node.
-            show_error (bool): If True, treat as error if node is not found.
+            nickname (str):
+                The nickname of the node.
+            show_error (bool):
+                If True, treat as error if node is not found.
 
         Returns:
             dict | None:
@@ -4315,7 +5131,7 @@ class OTCS:
                 The name of the attribute that includes the value to match with
             value (str):
                 The lookup value that is matched agains the node attribute value.
-            attribute_set (str, optional):
+            attribute_set (str | None, optional):
                 The name of the attribute set
 
         Returns:
@@ -4343,7 +5159,7 @@ class OTCS:
             )
             if not category_schema:
                 self.logger.debug(
-                    "Node -> '%s' (%s) does not have category -> '%s'. Cannot lookup -> '%s'. Skipping...",
+                    "Node -> '%s' (%s) does not have category -> '%s'. Cannot lookup value -> '%s'. Skipping...",
                     node_name,
                     node_id,
                     category,
@@ -4365,6 +5181,8 @@ class OTCS:
                 )
                 continue
             attribute_key = attribute_schema["key"]
+            # Split the attribute key once (1) at the first underscore from the right.
+            # rsplit delivers a list and [-1] delivers the last list item:
             attribute_id = attribute_key.rsplit("_", 1)[-1]
 
             if attribute_set:
@@ -4399,6 +5217,7 @@ class OTCS:
                         attribute_value = cat_data.get(key)
                         if not attribute_value:
                             break
+                        # Is it a multi-value attribute (i.e. a list of values)?
                         if isinstance(attribute_value, list):
                             if value in attribute_value:
                                 # Create a "results" dict that is compatible with normal REST calls
@@ -4437,89 +5256,6 @@ class OTCS:
 
     # end method definition
 
-    def lookup_node_old(
-        self,
-        parent_node_id: int,
-        category: str,
-        attribute: str,
-        value: str,
-    ) -> dict | None:
-        """Lookup the node under a parent node that has a specified value in a category attribute.
-
-        Args:
-            parent_node_id (int):
-                The node ID of the parent (typically folder or workspace).
-            category (str):
-                The name of the category.
-            attribute (str):
-                The name of the attribute that includes the value to match with
-            value (str):
-                The lookup value that is matched agains the node attribute value.
-
-        Returns:
-            dict | None:
-                Node wrapped in dictionary with "results" key or None if the REST API fails.
-
-        """
-
-        # get_subnodes_iterator() returns a python generator that we use for iterating over all nodes
-        # in an efficient way avoiding to retrieve all nodes at once (which could be a large number):
-        for node in self.get_subnodes_iterator(
-            parent_node_id=parent_node_id,
-            fields=["properties", "categories"],
-            metadata=True,
-        ):
-            schema = node["metadata"]["categories"]
-            data = node["data"]["categories"]
-            for cat_data, cat_schema in zip(data, schema, strict=False):
-                data_values = list(cat_data.values())
-                schema_values = list(cat_schema.values())
-                # Schema has one additional element (the first one) representing
-                # the category object itself. This includes the name. We need
-                # to remove (pop) it from the schema list to make sure the schema list
-                # and the data list have the same number of items. Otherwise
-                # the following for loop with zip() would not properly align the
-                # two lists:
-                category_name = schema_values.pop(0)["name"]
-                # Set attributes (standing for the set itself, not it's contained attributes)
-                # are only in the schema values, not in the data values. We need to remove
-                # them as well to avoid mis-alignment:
-                schema_values = [schema_value for schema_value in schema_values if schema_value.get("persona") != "set"]
-                if category_name == category:
-                    for attr_data, attr_schema in zip(
-                        data_values,
-                        schema_values,
-                        strict=False,
-                    ):
-                        attr_name = attr_schema["name"]
-                        if attr_name == attribute:
-                            if isinstance(attr_data, list):
-                                if value in attr_data:
-                                    # Create a "results" dict that is compatible with normal REST calls
-                                    # to not break get_result_value() method that may be called on the result:
-                                    return {"results": node}
-                            elif value == attr_data:
-                                # Create a results dict that is compatible with normal REST calls
-                                # to not break get_result_value() method that may be called on the result:
-                                return {"results": node}
-                    # we can break here and continue with the next node
-                    # as we had the right category but did not find the matching value
-                    break
-            # end for cat_data, cat_schema in zip(data, schema)
-        # end for node in nodes
-
-        self.logger.debug(
-            "Couldn't find a node with the value -> '%s' in the attribute -> '%s' of category -> '%s' in parent with node ID -> %s.",
-            value,
-            attribute,
-            category,
-            parent_node_id,
-        )
-
-        return None
-
-    # end method definition
-
     def lookup_node_by_regex(
         self,
         parent_node_id: int,
@@ -4861,13 +5597,18 @@ class OTCS:
             node_id (int):
                 ID of the node. You can use the get_volume() function below to
                 to the node id for a volume.
-            name (str): New name of the node.
-            description (str): New description of the node.
-            name_multilingual (dict, optional): multi-lingual node names
-            description_multilingual (dict, optional): multi-lingual description
+            name (str):
+                New name of the node.
+            description (str):
+                New description of the node.
+            name_multilingual (dict | None, optional):
+                The multi-lingual node names.
+            description_multilingual (dict | None, optional):
+                The multi-lingual descriptions.
 
         Returns:
-            dict | None: Request response or None if the renaming fails.
+            dict | None:
+                Request response or None if the renaming fails.
 
         """
 
@@ -5020,27 +5761,306 @@ class OTCS:
 
         """
 
-        request_url = self.config()["recycleBinUrl"] + "/nodes/restore"
-        request_header = self.request_form_header()
+        request_url = self.config()["recycleBinUrl"] + "/nodes/restore"
+        request_header = self.request_form_header()
+
+        restore_data = {"ids": node_id} if isinstance(node_id, list) else {"ids": [node_id]}
+
+        self.logger.debug(
+            "Restore node(s) with ID(s) -> %s from recycle bin; calling -> %s",
+            str(node_id),
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="POST",
+            headers=request_header,
+            data=restore_data,
+            timeout=None,
+            failure_message="Failed to restore node(s) with ID(s) -> {} from the recycle bin".format(
+                node_id,
+            ),
+        )
+
+    # end method definition
+
+    def get_node_audit(
+        self,
+        node_id: int,
+        filter_event_type: int | None = None,
+        filter_user_id: int | None = None,
+        filter_date_start: str | None = None,
+        filter_date_end: str | None = None,
+        limit: int = 100,
+        page: int = 1,
+        sort: str = "desc_audit_date",
+    ) -> dict | None:
+        """Get the audit information for a given node ID.
+
+        Args:
+            node_id (int):
+                The ID of the node to get the audit for.
+            filter_event_type (int | None, optional):
+                Type of audit events to filter by. Possible values:
+                - 9 : Permission Changed
+                - 10 : Attribute Value Changed
+                - 92 : Create from Copy
+                - 264 : Classification Applied
+                - 301 : Deployed from Warehouse
+                - 416 : XML Import
+                - 6000 : Content Sharing - Shared with external system
+                - 6014 : Content Sharing - Share Coordinator changed
+                - ...
+            filter_user_id (int, optional):
+                Filter audit events by user ID. Defaults to no filter.
+                The date should be provided in YYYY-MM-DD notation. Time
+                is not considered (only days)
+            filter_date_start (str | None, optional):
+                Filter audit events by start date. Defaults to no filter.
+                The date should be provided in YYYY-MM-DD notation. Time
+                is not considered (only days)
+            filter_date_end (str | None, optional):
+                Filter audit events by end date. Defaults to no filter.
+            limit (int, optional):
+                The maximum number of results to return. Defaults to 100.
+            page (int, optional):
+                The page of results to retrieve. Defaults to 1 (first page).
+            sort (str, optional):
+                Sort order of audit results. Format can be sort=desc_audit_date or sort=asc_audit_date.
+                Results are sorted in descending order by default.
+
+        Returns:
+            dict | None:
+                Subnode information as a dictionary, or None if no nodes with
+                the given parent ID are found.
+
+        Example:
+                {
+                    'collection': {
+                        'paging': {
+                            'limit': 100,
+                            'page': 1,
+                            'page_total': 1,
+                            'range_max': 23,
+                            'range_min': 1,
+                            'total_count': 23
+                        },
+                        'sorting': {
+                            'sort': [
+                                {
+                                    'key': 'sort',
+                                    'value': 'desc_audit_date'
+                                }
+                            ]
+                        }
+                    },
+                    'links': {
+                        'data': {
+                            'self': {
+                                'body': '',
+                                'content_type': '',
+                                'href': '/api/v2/nodes/29572/audit?fields=properties&limit=100&sort=desc_audit_date',
+                                'method': 'GET',
+                                'name': ''
+                            }
+                        }
+                    },
+                    'results': {
+                        'data': {
+                            'audit': [
+                                {
+                                    'id': 29572,
+                                    'event_type': 6000,
+                                    'audit_date': '2025-05-23T10:20:56Z',
+                                    'user_id': 8306,
+                                    'agent_id': None,
+                                    'audit_language_code': None,
+                                    'target_user_id': None,
+                                    'audit_name': 'Shared with Microsoft Teams Content Sharing Provider'
+                                },
+                                ...
+                            ],
+                            'audit_event_types': [
+                                {
+                                    'id': 92,
+                                    'name': 'Create from Copy'
+                                },
+                                {
+                                    'id': 6014,
+                                    'name': 'Content Sharing - Share Coordinators Changed'
+                                },
+                                {
+                                    'id': 301,
+                                    'name': 'Deployed from Warehouse'
+                                },
+                                ...
+                            ]
+                        }
+                    }
+                }
+
+        """
+
+        # Add query parameters (these are NOT passed via JSon body!)
+        query = {"limit": limit, "sort": sort}
+        if filter_event_type:
+            query["where_type"] = filter_event_type
+        if filter_user_id:
+            query["where_user_id"] = filter_user_id
+        if filter_date_start:
+            query["where_audit_date_start"] = filter_date_start
+        if filter_date_end:
+            query["where_audit_date_end"] = filter_date_end
+        if page > 1:
+            query["page"] = page
+
+        encoded_query = urllib.parse.urlencode(query=query, doseq=True)
+
+        request_url = self.config()["nodesUrlv2"] + "/" + str(node_id) + "/audit" + "?{}".format(encoded_query)
+
+        request_header = self.request_form_header()
+
+        self.logger.debug(
+            "Get audit of node with ID -> %s (page -> %d, item limit -> %d); calling -> %s",
+            str(node_id),
+            page,
+            limit,
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            failure_message="Failed to get audit for node with ID -> {}".format(
+                node_id,
+            ),
+        )
+
+    # end method definition
+
+    def get_node_audit_iterator(
+        self,
+        node_id: int,
+        filter_event_type: int | None = None,
+        filter_user_id: int | None = None,
+        filter_date_start: str | None = None,
+        filter_date_end: str | None = None,
+        page_size: int = 25,
+        sort: str = "desc_audit_date",
+    ) -> iter:
+        """Get an iterator object that can be used to traverse subnodes.
+
+        Filters can be applied that are given by the "filter" parameters.
+
+        Using a generator avoids loading a large number of nodes into memory at once.
+        Instead you can iterate over the potential large list of subnodes.
+
+        Example usage:
+            ```python
+            audit_entries = otcs_object.get_node_audit_iterator(node_id=15838)
+            for audit_entry in audit_entries:
+                logger.info("Audit entry -> '%s'", ...)
+            ```
+
+        Args:
+            node_id (int):
+                The ID of the node to get the audit for.
+            filter_event_type (int, optional):
+                Type of audit events to filter by. Possible values:
+                - 9 : Permission Changed
+                - 10 : Attribute Value Changed
+                - 92 : Create from Copy
+                - 264 : Classification Applied
+                - 301 : Deployed from Warehouse
+                - 416 : XML Import
+                - 6000 : Content Sharing - Shared with external system
+                - 6014 : Content Sharing - Share Coordinator changed
+                - ...
+            filter_user_id (int, optional):
+                Filter audit events by user ID. Defaults to no filter.
+                The date should be provided in YYYY-MM-DD notation. Time
+                is not considered (only days)
+            filter_date_start (str, optional):
+                Filter audit events by start date. Defaults to no filter.
+                The date should be provided in YYYY-MM-DD notation. Time
+                is not considered (only days)
+            filter_date_end (str, optional):
+                Filter audit events by end date. Defaults to no filter.
+            limit (int, optional):
+                The maximum number of results to return. Defaults to 100.
+            page (int, optional):
+                The page of results to retrieve. Defaults to 1 (first page).
+            sort (str, optional):
+                Sort order of audit results. Format can be sort=desc_audit_date or sort=asc_audit_date.
+                Results are sorted in descending order by default.
+            page_size (int, optional):
+                The number of subnodes that are requested per page.
+                For the iterator this is basically the chunk size.
+
+        Returns:
+            iter:
+                A generator yielding one node per iteration under the parent.
+                If the REST API fails, returns no value.
+
+        """
+
+        response = self.get_node_audit(
+            node_id=node_id,
+            filter_event_type=filter_event_type,
+            filter_user_id=filter_user_id,
+            filter_date_start=filter_date_start,
+            filter_date_end=filter_date_end,
+        )
+        if (
+            not response
+            or "collection" not in response
+            or "paging" not in response["collection"]
+            or not response["collection"]["paging"].get("total_count")
+        ):
+            self.logger.debug(
+                "Item with node ID -> %s has no audit information! Cannot iterate audit.",
+                str(node_id),
+            )
+            # Don't return None! Plain return is what we need for iterators.
+            # Natural Termination: If the generator does not yield, it behaves
+            # like an empty iterable when used in a loop or converted to a list:
+            return
 
-        restore_data = {"ids": node_id} if isinstance(node_id, list) else {"ids": [node_id]}
+        audit_size = response["collection"]["paging"]["total_count"]
 
-        self.logger.debug(
-            "Restore node(s) with ID(s) -> %s from recycle bin; calling -> %s",
-            str(node_id),
-            request_url,
-        )
+        # If the container has many items we need to go through all pages
+        # Adding page_size - 1 ensures that any remainder from the division is
+        # accounted for, effectively rounding up. Integer division (//) performs floor division,
+        # giving the desired number of pages:
+        total_pages = (audit_size + page_size - 1) // page_size
 
-        return self.do_request(
-            url=request_url,
-            method="POST",
-            headers=request_header,
-            data=restore_data,
-            timeout=None,
-            failure_message="Failed to restore node(s) with ID(s) -> {} from the recycle bin".format(
-                node_id,
-            ),
-        )
+        for page in range(1, total_pages + 1):
+            # Get the next page of sub node items:
+            response = self.get_node_audit(
+                node_id=node_id,
+                filter_event_type=filter_event_type,
+                filter_user_id=filter_user_id,
+                filter_date_start=filter_date_start,
+                filter_date_end=filter_date_end,
+                limit=page_size,
+                page=page,
+                sort=sort,
+            )
+            if not response or not response.get("results", None):
+                self.logger.warning(
+                    "Failed to retrieve audit for node ID -> %d (page -> %d)",
+                    node_id,
+                    page,
+                )
+                return None
+
+            # Yield nodes one at a time
+            yield from response["results"]["data"]["audit"]
+
+        # end for page in range(1, total_pages + 1)
 
     # end method definition
 
@@ -5123,11 +6143,14 @@ class OTCS:
         """Get Volume information based on the volume type ID.
 
         Args:
-            volume_type (int): ID of the volume type
-            timeout (int, optional): timeout for the request in seconds
+            volume_type (int):
+                The ID of the volume type.
+            timeout (int, optional):
+                The timeout for the request in seconds.
 
         Returns:
-            dict | None: Volume Details or None if volume is not found.
+            dict | None:
+                Volume details or None if volume is not found.
 
         Example:
             ["results"]["data"]["properties"]["id"] is the node ID of the volume.
@@ -5411,7 +6434,7 @@ class OTCS:
                         "12508_9": "MS Word",       # Text drop-down
                     }
                 }
-            classifications (list):
+            classifications (list | None, optional):
                 List of classification item IDs to apply to the new item.
             description (str, optional):
                 A description of the document.
@@ -5861,6 +6884,158 @@ class OTCS:
 
     # end method definition
 
+    def get_document_versions(self, node_id: str) -> list | None:
+        """Get a list of the document versions of a document node.
+
+        Args:
+            node_id (str):
+                Node ID of the document.
+
+        Returns:
+            list | None:
+                The list of document versions.
+
+        Example:
+        {
+            'links': {'data': {...}},
+            'results': [
+                {
+                    'data': {
+                        'versions': {
+                            'create_date': '2025-06-07T05:29:22Z',
+                            'description': '',
+                            'external_create_date': None,
+                            'external_identity': '',
+                            'external_identity_type': '',
+                            'external_modify_date': '2025-06-05T10:06:02',
+                            'external_source': 'file_system',
+                            'file_create_date': '2025-06-07T05:29:22Z',
+                            'file_modify_date': '2025-06-05T10:06:02Z',
+                            'file_name': 'OpenText-PPT-Presentation-FY25-LIGHT-FINAL.pptx',
+                            'file_size': 4057237,
+                            'file_type': 'pptx',
+                            'has_generation': False,
+                            'id': 107044,
+                            'locked': False,
+                            'locked_date': None,
+                            'locked_user_id': None,
+                            'mime_type': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+                            'modify_date': '2025-06-07T05:29:22Z',
+                            'name': 'OpenText-PPT-Presentation-FY25-LIGHT-FINAL.pptx',
+                            'owner_id': 1000,
+                            'provider_id': 103563,
+                            'version_id': 103564,
+                            'version_number': 2,
+                            'version_number_major': 0,
+                            'version_number_minor': 2,
+                            'version_number_name': '2'
+                        }
+                    }
+                }
+            ]
+        }
+
+        """
+
+        request_url = self.config()["nodesUrlv2"] + "/" + str(node_id) + "/versions"
+        request_header = self.request_form_header()
+
+        self.logger.debug(
+            "Get a list of all versions of document with node ID -> %s; calling -> %s",
+            str(node_id),
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            failure_message="Failed to get list of versions of document with node ID -> {}".format(
+                str(node_id),
+            ),
+        )
+
+    # end method definition
+
+    def get_document_version(self, node_id: str, version_number: int) -> dict | None:
+        """Get a particular version of a document based on the version number.
+
+        The first version (oldest) typically has the number 1.
+
+        Args:
+            node_id (str):
+                Node ID of the document.
+            version_number (int):
+                The version number.
+
+        Returns:
+            dict | None:
+                The version data.
+
+        Example:
+        {
+            'links': {'data': {...}},
+            'results': {
+                'data': {
+                    'versions': {
+                        'create_date': '2025-06-07T05:29:22Z',
+                        'description': '',
+                        'external_create_date': None,
+                        'external_identity': '',
+                        'external_identity_type': '',
+                        'external_modify_date': '2025-06-05T10:06:02',
+                        'external_source': 'file_system',
+                        'file_create_date': '2025-06-07T05:29:22Z',
+                        'file_modify_date': '2025-06-05T10:06:02Z',
+                        'file_name': 'OpenText-PPT-Presentation-FY25-LIGHT-FINAL.pptx',
+                        'file_size': 4057237,
+                        'file_type': 'pptx',
+                        'has_generation': False,
+                        'id': 107044,
+                        'locked': False,
+                        'locked_date': None,
+                        'locked_user_id': None,
+                        'mime_type': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+                        'modify_date': '2025-06-07T05:29:22Z',
+                        'name': 'OpenText-PPT-Presentation-FY25-LIGHT-FINAL.pptx',
+                        'owner_id': 1000,
+                        'provider_id': 103563,
+                        'version_id': 103564,
+                        'version_number': 2,
+                        'version_number_major': 0,
+                        'version_number_minor': 2,
+                        'version_number_name': '2'
+                    }
+                }
+            }
+        }
+
+        """
+
+        request_url = self.config()["nodesUrlv2"] + "/" + str(node_id) + "/versions/" + str(version_number)
+        request_header = self.request_form_header()
+
+        self.logger.debug(
+            "Get version -> %d of document with node ID -> %s; calling -> %s",
+            version_number,
+            str(node_id),
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            failure_message="Failed to get version -> {} of document with node ID -> {}".format(
+                version_number,
+                str(node_id),
+            ),
+        )
+
+    # end method definition
+
     def get_latest_document_version(self, node_id: int) -> dict | None:
         """Get latest version of a document node based on the node ID.
 
@@ -5874,6 +7049,7 @@ class OTCS:
 
         """
 
+        # This Method requires V1of the REST API!
         request_url = self.config()["nodesUrl"] + "/" + str(node_id) + "/versions/latest"
         request_header = self.request_form_header()
 
@@ -5895,6 +7071,63 @@ class OTCS:
 
     # end method definition
 
+    def purge_document_versions(self, node_id: int, versions_to_keep: int = 1) -> dict | None:
+        """Purge versions of a document based on the node ID of the document.
+
+        Args:
+            node_id (int):
+                The ID of the document node to purge versions for.
+            versions_to_keep (int):
+                Number of versions to keep (from the newest to the oldest).
+                The minimum allowed number is 1. This is also the default.
+                If 1 is provided it means to keep the nerwest version only.
+
+        Returns:
+            dict | None:
+                The result data or None if the request fails.
+
+        Example:
+        {
+            'links': {'data': {...}},
+            'results': {}
+        }
+
+        """
+
+        # Sanity check:
+        if versions_to_keep < 1:
+            self.logger.error("Purging to less than 1 version is not possible. The value -> %d is not valid!")
+            return None
+
+        request_url = self.config()["nodesUrlv2"] + "/" + str(node_id) + "/versions"
+        request_header = self.request_form_header()
+
+        purge_delete_body = {
+            "number_to_keep": versions_to_keep,
+        }
+
+        self.logger.debug(
+            "Purge document versions down to the newest%s version%s of document with node ID -> %s; calling -> %s",
+            " {}".format(versions_to_keep) if versions_to_keep > 1 else "",
+            "s" if versions_to_keep > 1 else "",
+            str(node_id),
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="DELETE",
+            headers=request_header,
+            data=purge_delete_body,
+            timeout=None,
+            failure_message="Failed to purge to {} versions of document with node ID -> {}".format(
+                versions_to_keep,
+                str(node_id),
+            ),
+        )
+
+    # end method definition
+
     def get_document_content(
         self,
         node_id: int,
@@ -5945,7 +7178,7 @@ class OTCS:
             method="GET",
             headers=request_header,
             timeout=None,
-            failure_message="Failed to download document with node ID -> {}".format(
+            failure_message="Failed to get content of document with node ID -> {}".format(
                 node_id,
             ),
             parse_request_response=parse_request_response,
@@ -5969,16 +7202,19 @@ class OTCS:
         node_id: int,
         version_number: str = "",
     ) -> list | dict | None:
-        """Get document content from Extended ECM and read content as JSON.
+        """Get document content from Content Server and parse content as JSON.
 
         Args:
-            node_id (int): The node ID of the document to download
-            version_number (str, optional): The version of the document to download.
-                                            If version = "" then download the latest
-                                            version.
+            node_id (int):
+                The node ID of the document to download
+            version_number (str, optional):
+                The version of the document to download.
+                If version = "" then download the latest
+                version.
 
         Returns:
-            list | dict | None: Content of the file or None in case of an error.
+            list | dict | None:
+                Content of the file or None in case of an error.
 
         """
 
@@ -5994,16 +7230,16 @@ class OTCS:
         self,
         node_id: int,
         file_path: str,
-        version_number: str = "",
+        version_number: str | int = "",
     ) -> bool:
-        """Download a document from Extended ECM to local file system.
+        """Download a document from OTCS to local file system.
 
         Args:
             node_id (int):
                 The node ID of the document to download
             file_path (str):
                 The local file path (directory).
-            version_number (str, optional):
+            version_number (str | int, optional):
                 The version of the document to download.
                 If version = "" then download the latest version.
 
@@ -6525,14 +7761,17 @@ class OTCS:
         connection_name: str,
         show_error: bool = False,
     ) -> dict | None:
-        """Get Extended ECM external system connection (e.g. SAP, Salesforce, SuccessFactors).
+        """Get external system connection (e.g. SAP, Salesforce, SuccessFactors).
 
         Args:
-            connection_name (str): Name of the connection
-            show_error (bool, optional): If True, treat as error if connection is not found.
+            connection_name (str):
+                The name of the connection to an external system.
+            show_error (bool, optional):
+                If True, treat as error if connection is not found.
 
         Returns:
-            dict | None: External system Details or None if the REST call fails.
+            dict | None:
+                External system Details or None if the REST call fails.
 
         """
         # Encode special characters in connection_name
@@ -6570,7 +7809,7 @@ class OTCS:
         base_url: str,
         username: str,
         password: str,
-        authentication_method: str = "BASIC",  # either BASIC or OAUTH
+        authentication_method: str = "BASIC",
         client_id: str | None = None,
         client_secret: str | None = None,
     ) -> dict | None:
@@ -6591,9 +7830,9 @@ class OTCS:
                 The password (used for BASIC authentication)
             authentication_method (str, optional):
                 Either BASIC (using username and password) or OAUTH.
-            client_id (str, optional):
+            client_id (str | None, optional):
                 The OAUTH Client ID (only required if authenticationMethod = OAUTH).
-            client_secret (str, optional):
+            client_secret (str | None, optional):
                 OAUTH Client Secret (only required if authenticationMethod = OAUTH).
 
         Returns:
@@ -6799,12 +8038,12 @@ class OTCS:
                 Name of the transport package ZIP file.
             package_description (str, optional):
                 Description of the transport package. Default is an empty string.
-            replacements (list of dicts, optional):
+            replacements (list[dict] | None, optional):
                 List of replacement values to be applied to all XML files in the transport.
                 Each dictionary must contain:
                 - 'placeholder': text to replace
                 - 'value': text to replace with
-            extractions (list of dicts, optional):
+            extractions (list[dict] | None, optional):
                 List of XML subtrees to extract from each XML file in the transport.
                 Each dictionary must contain:
                 - 'xpath': defining the subtree to extract
@@ -7029,14 +8268,16 @@ class OTCS:
         """Search and replace strings in the XML files of the transport package.
 
         Args:
-            zip_file_path (str): Path to transport zip file.
-            replacements (list of dicts):
+            zip_file_path (str):
+                Path to transport zip file.
+            replacements (list[dict]):
                 List of replacement values; dict needs to have two values:
                 - placeholder: The text to replace.
                 - value: The replacement text.
 
         Returns:
-            bool: True = success, False = error.
+            bool:
+                True = success, False = error.
 
         """
 
@@ -7175,7 +8416,8 @@ class OTCS:
         """Search and extract XML data from the transport package.
 
         Args:
-            zip_file_path (str): Path to transport zip file.
+            zip_file_path (str):
+                Path to transport zip file.
             extractions (list of dicts):
                 List of extraction values; dict needs to have two values:
                 - xpath: structure to find
@@ -7419,9 +8661,9 @@ class OTCS:
             where_clauses (dict | None, optional):
                 Filter the results based on one or multiple where clauses.
                 TODO: NAME CONVENTION FOR THE FIELDS
-            limit (int, optional):
+            limit (int | None, optional):
                 The maximum number of result items.
-            page (int, optional):
+            page (int | None, optional):
                 The page number for a chunked result list.
 
         Returns:
@@ -7581,7 +8823,7 @@ class OTCS:
         """Get all workspace types configured in Extended ECM.
 
         This REST API is very limited. It does not return all workspace type properties
-        you can see in Extended ECM admin page.
+        you can see in OTCS business admin page.
 
         Args:
             expand_workspace_info (bool, optional):
@@ -8393,11 +9635,11 @@ class OTCS:
         Args:
             workspace_id (int):
                 The ID of the workspace.
-            external_system_id (str, optional):
+            external_system_id (str | None, optional):
                 Identifier of the external system (None if no external system).
-            bo_type (str, optional):
+            bo_type (str | None, optional):
                 Business object type (None if no external system)
-            bo_id (str, optional):
+            bo_id (str | None, optional):
                 Business object identifier / key (None if no external system)
             show_error (bool, optional):
                 Log an error if workspace cration fails. Otherwise log a warning.
@@ -9213,10 +10455,12 @@ class OTCS:
         """Get the Workspace roles.
 
         Args:
-            workspace_id (int): ID of the workspace template or workspace
+            workspace_id (int):
+                The ID of the workspace template or workspace.
 
         Returns:
-            dict | None: Workspace Roles data or None if the request fails.
+            dict | None:
+                Workspace Roles data or None if the request fails.
 
         """
 
@@ -9245,11 +10489,14 @@ class OTCS:
         """Get the Workspace members of a given role.
 
         Args:
-            workspace_id (int): ID of the workspace template
-            role_id (int): ID of the role
+            workspace_id (int):
+                The ID of the workspace.
+            role_id (int):
+                The ID of the workspace role.
 
         Returns:
-            dict | None: Workspace member data or None if the request fails.
+            dict | None:
+                Workspace member data or None if the request fails.
 
         """
 
@@ -9268,7 +10515,9 @@ class OTCS:
             method="GET",
             headers=request_header,
             timeout=None,
-            failure_message="Failed to get workspace members",
+            failure_message="Failed to get workspace members for workspace with ID -> {} and role with ID -> {}".format(
+                workspace_id, role_id
+            ),
         )
 
     # end method definition
@@ -9283,13 +10532,18 @@ class OTCS:
         """Add member to a workspace role. Check that the user/group is not yet a member.
 
         Args:
-            workspace_id (int): ID of the workspace
-            role_id (int): ID of the role
-            member_id (int): User ID or Group ID
-            show_warning (bool, optional): If True logs a warning if member is already in role
+            workspace_id (int):
+                The ID of the workspace.
+            role_id (int):
+                The ID of the workspace role.
+            member_id (int):
+                The user ID or group ID.
+            show_warning (bool, optional):
+                If True logs a warning if member is already in role.
 
         Returns:
-            dict | None: Workspace Role Membership or None if the request fails.
+            dict | None:
+                Workspace Role Membership or None if the request fails.
 
         """
 
@@ -9357,13 +10611,18 @@ class OTCS:
         """Remove a member from a workspace role. Check that the user is currently a member.
 
         Args:
-            workspace_id (int): ID of the workspace
-            role_id (int): ID of the role
-            member_id (int): User or Group Id
-            show_warning (bool, optional): If True logs a warning if member is not in role
+            workspace_id (int):
+                The ID of the workspace.
+            role_id (int):
+                The ID of the workspace role.
+            member_id (int):
+                The user or Group ID.
+            show_warning (bool, optional):
+                If True logs a warning if member is not in role.
 
         Returns:
-            dict | None: Workspace Role Membership or None if the request fails.
+            dict | None:
+                Workspace Role Membership or None if the request fails.
 
         """
 
@@ -9431,12 +10690,16 @@ class OTCS:
         """Remove all members from a workspace role. Check that the user is currently a member.
 
         Args:
-            workspace_id (int): ID of the workspace
-            role_id (int): ID of the role
-            show_warning (bool, optional): If True, logs a warning if member is not in role
+            workspace_id (int):
+                The ID of the workspace.
+            role_id (int):
+                The ID of the workspace role.
+            show_warning (bool, optional):
+                If True, logs a warning if member is not in role.
 
         Returns:
-            bool: True if success or False if the request fails.
+            bool:
+                True if success or False if the request fails.
 
         """
 
@@ -9478,9 +10741,12 @@ class OTCS:
         specifying whether to apply these permissions to the item itself, its sub-items, or both.
 
         Args:
-            workspace_id (int): ID of the workspace for which the role permissions are being assigned.
-            role_id (int): ID of the role to which the permissions will be assigned.
-            permissions (list of str): List of permissions to assign to the role. Valid permissions include:
+            workspace_id (int):
+                The ID of the workspace for which the role permissions are being assigned.
+            role_id (int):
+                The ID of the role to which the permissions will be assigned.
+            permissions (list):
+                List of permissions to assign to the role. Valid permissions include:
                 - "see"               : View the workspace
                 - "see_contents"      : View contents of the workspace
                 - "modify"            : Modify the workspace
@@ -9491,14 +10757,16 @@ class OTCS:
                 - "delete_versions"   : Delete versions of the workspace
                 - "delete"            : Delete the workspace
                 - "edit_permissions"  : Modify permissions for the workspace
-            apply_to (int, optional): Specifies the scope of permission assignment. Possible values:
+            apply_to (int, optional):
+                Specifies the scope of permission assignment. Possible values:
                 - 0 = Apply to this item only
                 - 1 = Apply to sub-items only
                 - 2 = Apply to this item and its sub-items (default)
                 - 3 = Apply to this item and its immediate sub-items
 
         Returns:
-            dict | None: Updated workspace role membership details or `None` if the request fails.
+            dict | None:
+                Updated workspace role membership details or `None` if the request fails.
 
         Notes:
             - If `apply_to` is set to `2`, both the workspace and its sub-items will inherit the updated permissions.
@@ -9549,12 +10817,16 @@ class OTCS:
         """Update a workspace with a with a new icon (which is uploaded).
 
         Args:
-            workspace_id (int): ID of the workspace
-            file_path (str): path + filename of icon file
-            file_mimetype (str, optional): mimetype of the image
+            workspace_id (int):
+                The ID of the workspace to update the icon for.
+            file_path (str):
+                The path + filename of icon file.
+            file_mimetype (str, optional):
+                The mimetype of the image.
 
         Returns:
-            dict | None: Node information or None if REST call fails.
+            dict | None:
+                Node information or None if REST call fails.
 
         """
 
@@ -9609,11 +10881,14 @@ class OTCS:
         """Get definition information for Unique Names.
 
         Args:
-            names (list): list of unique names to lookup.
-            subtype (int): filter unique names for those pointing to a specific subtype
+            names (list):
+                A list of unique names to lookup.
+            subtype (int):
+                A subtype ID to filter unique names to those pointing to a specific subtype.
 
         Returns:
-            dict | None: Unique name definition information or None if REST call fails.
+            dict | None:
+                Unique name definition information or None if REST call fails.
 
         Example:
             ```json
@@ -9878,12 +11153,12 @@ class OTCS:
                 Address of the URL item (if it is an URL item type).
             category_data (dict | None, optional):
                 New category and attributes values.
-            classifications (list):
+            classifications (list | None, optional):
                 List of classification item IDs to apply to the new item.
-            body (bool):
+            body (bool, optional):
                 Should the payload be put in an body tag. Most V2 REST API methods
                 do require this but some not (like Scheduled Bots)
-            **kwargs (dict):
+            **kwargs (dict, optional):
                 Add additional attributes to the body of the POST request
 
         Returns:
@@ -9971,9 +11246,9 @@ class OTCS:
         Args:
             parent_id (int):
                 The node the category should be applied to.
-            subtype (int):
+            subtype (int, optional):
                 The subtype of the new node. Default is document.
-            category_ids (int | list[int]):
+            category_ids (int | list[int], optional):
                 The ID of the category or a list of category IDs.
 
         Returns:
@@ -10273,7 +11548,7 @@ class OTCS:
         description: str = "",
         show_error: bool = True,
     ) -> dict | None:
-        """Create an Extended ECM wiki page.
+        """Create an OTCS wiki page.
 
         Args:
             wiki_id (int):
@@ -10327,7 +11602,7 @@ class OTCS:
     # end method definition
 
     def get_web_report_parameters(self, nickname: str) -> list | None:
-        """Retrieve parameters of a Web Report in Extended ECM.
+        """Retrieve parameters of a Web Report in OTCS.
 
         These parameters are defined on the Web Report node (Properties -> Parameters).
 
@@ -10384,14 +11659,17 @@ class OTCS:
         nickname: str,
         web_report_parameters: dict | None = None,
     ) -> dict | None:
-        """Run a Web Report that is identified by its nick name.
+        """Run a Web Report that is identified by its nickname.
 
         Args:
-            nickname (str): nickname of the Web Reports node.
-            web_report_parameters (dict, optional): Parameters of the Web Report (names + value pairs)
+            nickname (str):
+                The nickname of the Web Reports node.
+            web_report_parameters (dict, optional):
+                Parameters of the Web Report (names + value pairs)
 
         Returns:
-            dict | None: Response of the run Web Report request or None if the Web Report execution has failed.
+            dict | None:
+                Response of the run Web Report request or None if the Web Report execution has failed.
 
         """
 
@@ -10403,7 +11681,7 @@ class OTCS:
         request_header = self.request_form_header()
 
         self.logger.debug(
-            "Running Web Report with nickname -> %s; calling -> %s",
+            "Running Web Report with nickname -> '%s'; calling -> %s",
             nickname,
             request_url,
         )
@@ -10467,11 +11745,11 @@ class OTCS:
     ) -> dict | None:
         """Assign an Content Server item to users and groups.
 
-        This is a function used by Extended ECM for Government.
+        This is a function used by OT Content Management for Government.
 
         Args:
             node_id (int):
-                The node ID of the Extended ECM item (e.g. a workspace or a document)
+                The node ID of the OTCS item (e.g. a workspace or a document)
             subject (str):
                 The title / subject of the assignment.
             instruction (str):
@@ -10598,28 +11876,19 @@ class OTCS:
     def assign_permission(
         self,
         node_id: int,
-        assignee_type: str,
-        assignee: int,
         permissions: list,
+        assignee_type: str,
+        assignee: int = 0,
         apply_to: int = 0,
     ) -> dict | None:
-        """Assign permissions to a user or group for an Extended ECM item.
+        """Assign permissions to a user or group for an Content Server item.
 
         This method allows you to assign specified permissions to a user or group for a given
         Content Server item (node). The permissions can be applied to the item itself, its sub-items,
         or both.
 
         Args:
-            node_id (int): The ID of the Extended ECM item (node) to which permissions are being assigned.
-            assignee_type (str): The type of assignee. This can be one of the following:
-                - "owner": Permissions are assigned to the owner.
-                - "group": Permissions are assigned to the owner group.
-                - "public": Permissions are assigned to the public (all users).
-                - "custom": Permissions are assigned to a specific user or group (specified by `assignee`).
-            assignee (int):
-                The ID of the user or group (referred to as "right ID").
-                If `assignee` is 0 and `assignee_type` is "owner" or "group",
-                the owner or group will not be changed.
+            node_id (int): The ID of the OTCS item (node) to which permissions are being assigned.
             permissions (list of str): A list of permissions to assign to the assignee. Valid permissions include:
                 - "see"               : View the item
                 - "see_contents"      : View the contents of the item
@@ -10631,6 +11900,15 @@ class OTCS:
                 - "delete_versions"   : Delete versions of the item
                 - "delete"            : Delete the item
                 - "edit_permissions"  : Modify permissions for the item
+            assignee_type (str): The type of assignee. This can be one of the following:
+                - "owner": Permissions are assigned to the owner.
+                - "group": Permissions are assigned to the owner group.
+                - "public": Permissions are assigned to the public (all users).
+                - "custom": Permissions are assigned to a specific user or group (specified by `assignee`).
+            assignee (int):
+                The ID of the user or group (referred to as "right ID").
+                If `assignee` is 0 and `assignee_type` is "owner" or "group",
+                the owner or group will not be changed.
             apply_to (int, optional): The scope of the permission assignment. Possible values:
                 - 0 = Apply to this item only (default)
                 - 1 = Apply to sub-items only
@@ -10647,18 +11925,24 @@ class OTCS:
 
         """
 
-        if not assignee_type or assignee_type not in [
-            "owner",
-            "group",
-            "public",
-            "custom",
-        ]:
+        if not assignee_type or assignee_type not in OTCS.PERMISSION_ASSIGNEE_TYPES:
             self.logger.error(
-                "Missing or wrong assignee type. Needs to be owner, group, public or custom!",
+                "Missing or wrong assignee type. Needs to be one of %s!", str(OTCS.PERMISSION_ASSIGNEE_TYPES)
             )
             return None
         if assignee_type == "custom" and not assignee:
-            self.logger.error("Missing permission assignee!")
+            self.logger.error("Assignee type is 'custom' but permission assignee is missing!")
+            return None
+
+        if any(permission not in OTCS.PERMISSION_TYPES for permission in permissions):
+            illegal_permissions = [permission for permission in permissions if permission not in OTCS.PERMISSION_TYPES]
+            self.logger.error(
+                "Illegal permission%s -> %s! Allowed permissions are -> %s. Cannot assign permissions to node with ID -> %d.",
+                "s" if len(illegal_permissions) > 1 else "",
+                str(illegal_permissions),
+                str(OTCS.PERMISSION_TYPES),
+                node_id,
+            )
             return None
 
         permission_post_data = {
@@ -10676,10 +11960,11 @@ class OTCS:
         request_header = self.request_form_header()
 
         self.logger.debug(
-            "Assign permissions -> %s to item with ID -> %s; assignee type -> '%s'; calling -> %s",
+            "Assign permissions -> %s to item with ID -> %s; assignee type -> '%s'; apply to -> '%d'; calling -> %s",
             str(permissions),
             str(node_id),
             assignee_type,
+            apply_to,
             request_url,
         )
 
@@ -10692,9 +11977,8 @@ class OTCS:
                 headers=request_header,
                 data={"body": json.dumps(permission_post_data)},
                 timeout=None,
-                failure_message="Failed to assign custom permissions -> {} to item with ID -> {}".format(
-                    permissions,
-                    node_id,
+                failure_message="Failed to assign 'custom' permissions -> {} to item with ID -> {} (apply to -> {})".format(
+                    permissions, node_id, apply_to
                 ),
             )
         else:
@@ -10705,9 +11989,8 @@ class OTCS:
                 headers=request_header,
                 data={"body": json.dumps(permission_post_data)},
                 timeout=None,
-                failure_message="Failed to assign stadard permissions -> {} to item with ID -> {}".format(
-                    permissions,
-                    node_id,
+                failure_message="Failed to assign -> '{}' permissions -> {} to item with ID -> {} (apply to -> {})".format(
+                    assignee_type, permissions, node_id, apply_to
                 ),
             )
 
@@ -11156,8 +12439,10 @@ class OTCS:
         throw an error.
 
         Args:
-            node_id (int): node ID to apply the category to
-            category_id (list): ID of the category definition object
+            node_id (int):
+                The node ID to apply the category to.
+            category_id (list):
+                The ID of the category definition object.
             inheritance (bool | None):
                 If True, turn on inheritance for the category
                 (this makes only sense if the node is a container like a folder or workspace).
@@ -13340,11 +14625,14 @@ class OTCS:
         """Get a list of available workflows for a document ID and a parent ID.
 
         Args:
-            node_id (int): node ID of the document
-            parent_id (int): node ID of the parent
+            node_id (int):
+                The node ID of the document.
+            parent_id (int):
+                The node ID of the parent.
 
         Returns:
-            list: list of available workflows
+            list:
+                The list of available workflows.
 
         Example:
             ```json
@@ -14375,44 +15663,295 @@ class OTCS:
 
     # end method definition
 
-    def volume_translator(
+    def traverse_node(
         self,
-        current_node_id: int,
-        translator: object,
-        languages: list,
-        simulate: bool = False,
-    ) -> None:
-        """Experimental code to translate the item names and descriptions in a hierarchy.
+        node: dict | int,
+        executables: list[callable],
+        current_depth: int = 0,
+        **kwargs: dict,
+    ) -> dict:
+        """Recursively traverse the node an its subnodes.
+
+        This method is preferred for CPU intensive traversals.
+
+        Args:
+            node (dict | int):
+                The node datastructure (like in a V2 REST Call response)
+            executables (list[callable]):
+                A list of methods to call for each traversed node. The node
+                and a optional dictionary of keyword arguments (kwargs)
+                are passed. The executables are called BEFORE the subnodes
+                are traversed. The executables should return a boolean result.
+                If the result is False, then the execution of the executables
+                list is stopped.
+            current_depth (int, optional):
+                The recursion depth - distance in hierarchy from the root note
+                traverse_node() was INITIALLY called from.
+            kwargs:
+                Additional keyword arguments for the executables.
+
+        Returns:
+            dict: {
+                "processed": int,
+                "traversed": int,
+            }
+
+        """
+
+        processed = 0
+        traversed = 0
+
+        # Initialze the traverse flag. If True, container
+        # subnodes will be processed. If executables exist
+        # than at least one executable has to indicate that
+        # further traversal is required:
+        traverse = not (executables)
+
+        if isinstance(node, dict):
+            node_id = self.get_result_value(response=node, key="id")
+        elif isinstance(node, int):
+            node_id = node
+            node = self.get_node(node_id=node_id)
+        else:
+            self.logger.error("Illegal type of node object. Expect 'int' or 'dict'!")
+            return (False, False)
+
+        # Run executables:
+        for executable in executables:
+            result_success, result_traverse = executable(node=node, current_depth=current_depth, **kwargs)
+            if result_traverse:
+                traverse = True
+            if not result_success:
+                break
+        else:
+            # else case is processed only if NO break occured in the for loop
+            # If all executables have been successful than the node counts as processed:
+            processed += 1
+
+        node_type = self.get_result_value(response=node, key="type")
+
+        # We only traverse the subtnodes if the current node is a container type
+        # and the executables have all been executed successfully:
+        if traverse and node_type in self.CONTAINER_ITEM_TYPES:
+            # Get children nodes of the current node:
+            subnodes = self.get_subnodes_iterator(parent_node_id=node_id, page_size=200)
+
+            # Recursive call of all subnodes:
+            for subnode in subnodes:
+                subnode_id = self.get_result_value(response=subnode, key="id")
+                subnode_name = self.get_result_value(response=subnode, key="name")
+                self.logger.info("Traversing node -> '%s' (%s)", subnode_name, str(subnode_id))
+                # Recursive call for current subnode:
+                result = self.traverse_node(
+                    node=subnode,
+                    executables=executables,
+                    current_depth=current_depth + 1,
+                    **kwargs,
+                )
+                processed += result.get("processed", 0)
+                traversed += result.get("traversed", 0)
+            traversed += 1
+
+        return {"processed": processed, "traversed": traversed}
+
+    # end method definition
+
+    def traverse_node_parallel(
+        self,
+        node: dict | int,
+        executables: list[callable],
+        workers: int = 3,
+        strategy: str = "BFS",
+        timeout: float = 1.0,
+        **kwargs: dict,
+    ) -> dict:
+        """Traverse nodes using a queue and thread pool (BFS-style).
+
+        This method is preferred for I/O or API intensive traversals.
+
+        Args:
+            node (dict | int):
+                Root node to start traversal. It can be a node or a node ID.
+            executables (list[callable]):
+                Callables to execute per node.
+            workers (int, optional):
+                Number of parallel workers.
+            strategy (str, optional):
+                Either "DFS" for Depth First Search, or "BFS" for Breadth First Search.
+                "BFS" is the default.
+            timeout (float, optional):
+                Wait time for the queue to have items:
+            kwargs (dict):
+                Additional arguments for executables.
+
+        Returns:
+            dict:
+                Stats with processed and traversed counters.
+
+        """
+
+        results = {"processed": 0, "traversed": 0}
+        lock = threading.Lock()
+        if strategy == "BFS":
+            task_queue = Queue()
+        elif strategy == "DFS":
+            task_queue = LifoQueue()
+
+        # Enqueue initial nodes at depth 0:
+        node_id = self.get_result_value(response=node, key="id") if isinstance(node, dict) else node
+        subnodes = self.get_subnodes_iterator(parent_node_id=node_id, page_size=100)
+        for subnode in subnodes:
+            # Each queue element needs its own copy of traversal data:
+            traversal_data = {
+                "folder_path": [],
+                "workspace_id": None,
+                "workspace_type": None,
+                "workspace_name": None,
+                "workspace_description": None,
+                "current_depth": 0,
+            }
+            task_queue.put((subnode, 0, traversal_data))
+
+        def traverse_node_worker() -> None:
+            """Work on queue.
+
+            Returns:
+                None
+
+            """
+
+            thread_name = threading.current_thread().name
+
+            while True:
+                # Initialze the traverse flag. If True, container
+                # subnodes will be processed. If executables exist
+                # than at least one executable has to return that
+                # further traversal is required:
+                traverse = not (executables)
+
+                try:
+                    node, current_depth, traversal_data = task_queue.get(timeout=timeout)
+                except Empty:
+                    self.logger.info("[%s] No (more) nodes to process - finishing...", thread_name)
+                    return  # Queue is empty - worker is done
+
+                try:
+                    # Fetch node dictionary if just an ID was passed as parameter:
+                    if isinstance(node, int):
+                        node = self.get_node(node_id=node)
+
+                    node_id = self.get_result_value(response=node, key="id")
+                    node_name = self.get_result_value(response=node, key="name")
+                    node_type = self.get_result_value(response=node, key="type")
+
+                    self.logger.info(
+                        "[%s] Traversing node -> '%s' (%s) at depth %d", thread_name, node_name, node_id, current_depth
+                    )
+
+                    # Run all executables
+                    for executable in executables:
+                        try:
+                            result_success, result_traverse = executable(
+                                node=node,
+                                current_depth=current_depth,
+                                traversal_data=traversal_data,
+                                **kwargs,
+                            )
+                            if result_traverse:
+                                traverse = True
+                            if not result_success:
+                                break
+                        except Exception as e:
+                            self.logger.error("Failed to run executable on node -> '%s' (%s), error -> %s", node_name, node_id, str(e))
+                    else:
+                        with lock:
+                            results["processed"] += 1
+
+                    # We only traverse the subtnodes if the current node is a container type
+                    # and at least one executables (if they any) indicate to require further traversal:
+                    if traverse and node_type in self.CONTAINER_ITEM_TYPES:
+                        subnodes = self.get_subnodes_iterator(parent_node_id=node_id, page_size=100)
+                        for subnode in subnodes:
+                            sub_traversal_data = {
+                                **traversal_data,
+                                "folder_path": traversal_data["folder_path"] + [node_name],
+                                "current_depth": current_depth + 1,
+                            }
+                            task_queue.put((subnode, current_depth + 1, sub_traversal_data))
+
+                        with lock:
+                            results["traversed"] += 1
+
+                finally:
+                    # Guarantee task_done() is called even if exceptions occur:
+                    task_queue.task_done()
+
+        # end method traverse_node_worker()
+
+        # Start thread pool with limited concurrency
+        with ThreadPoolExecutor(max_workers=workers, thread_name_prefix="Traversal_Worker") as executor:
+            for i in range(workers):
+                self.logger.info("Starting worker -> %d...", i)
+                executor.submit(traverse_node_worker)
+
+            # Wait for all tasks to complete
+            task_queue.join()
+
+        return results
+
+    # end method definition
+
+    def translate_node(self, node: dict | int, **kwargs: dict) -> bool:
+        """Translate a node.
 
         The actual translation is done by a tranlator object. This recursive method just
         traverses the hierarchy and calls the translate() method of the translator object.
 
         Args:
-            current_node_id (int):
-                The current node ID to translate.
-            translator (object):
-                This object needs to be created based on the "Translator" class
-                and passed to this method.
-            languages (list):
-                A list of target languages to translate into.
-            simulate (bool, optional):
-                If True, do not really rename but just traverse and log info.
-                The default is False.
+            node (dict | int):
+                The current node to translate. This can be the node data structure or just
+                the node ID. If it is just the ID the actual node will be fetched.
+            kwargs (dict):
+                Keyword parameters. The methods expects the follwoing keyword parameters:
+                * simulate (bool):
+                    If True, do not really rename but just traverse and log info.
+                * translator (object):
+                    This object needs to be created based on the "Translator" class
+                    and passed to this method.
+                * languages (list):
+                    A list of target languages to translate into.
+
+        Returns:
+            bool:
+                True for success, False for error.
 
         """
 
-        # Get current node based on the ID:
-        current_node = self.get_node(current_node_id)
-        current_node_id = self.get_result_value(response=current_node, key="id")
+        translator = kwargs.get("translator")
+        languages = kwargs.get("languages", [])
+        simulate = kwargs.get("simulate", False)
+
+        if not translator:
+            self.logger.error("Missing 'translator' parameter (object)!")
+            return False
+        if not languages:
+            self.logger.error("Missing or empty 'languages' parameter (list)!")
+            return False
+
+        if isinstance(node, dict):
+            current_node_id = self.get_result_value(response=node, key="id")
+        else:
+            current_node_id = node
+            node = self.get_node(node_id=current_node_id)
 
-        name = self.get_result_value(response=current_node, key="name")
-        description = self.get_result_value(response=current_node, key="description")
+        name = self.get_result_value(response=node, key="name")
+        description = self.get_result_value(response=node, key="description")
         names_multilingual = self.get_result_value(
-            response=current_node,
+            response=node,
             key="name_multilingual",
         )
         descriptions_multilingual = self.get_result_value(
-            response=current_node,
+            response=node,
             key="description_multilingual",
         )
 
@@ -14427,7 +15966,7 @@ class OTCS:
                     language,
                     names_multilingual["en"],
                 )
-                self.logger.debug(
+                self.logger.info(
                     "Translate name of node -> %s from -> '%s' (%s) to -> '%s' (%s)",
                     current_node_id,
                     name,
@@ -14445,7 +15984,7 @@ class OTCS:
                     language,
                     descriptions_multilingual["en"],
                 )
-                self.logger.debug(
+                self.logger.info(
                     "Translate description of node -> %s from -> '%s' (%s) to -> '%s' (%s)",
                     current_node_id,
                     descriptions_multilingual["en"],
@@ -14456,24 +15995,17 @@ class OTCS:
 
         # Rename node multi-lingual:
         if not simulate:
-            self.rename_node(
+            response = self.rename_node(
                 node_id=current_node_id,
                 name=name,
                 description=description,
                 name_multilingual=names_multilingual,
                 description_multilingual=descriptions_multilingual,
             )
+            if not response:
+                return False
 
-        # Get children nodes of the current node:
-        results = self.get_subnodes(parent_node_id=current_node_id, limit=200)["results"]
-
-        # Recursive call of all subnodes:
-        for result in results:
-            self.volume_translator(
-                current_node_id=result["data"]["properties"]["id"],
-                translator=translator,
-                languages=languages,
-            )
+        return True
 
     # end method definition
 
@@ -15311,10 +16843,12 @@ class OTCS:
                         subnode["id"],
                         subnode["type"],
                     )
+            # end match subnode["type"]:
 
             # Wait for all download threads to complete:
             for thread in download_threads:
                 thread.join()
+        # end for subnode in subnodes:
 
         # Wait for all traversal threads to complete:
         for thread in traversal_threads:
@@ -15324,6 +16858,481 @@ class OTCS:
 
     # end method definition
 
+    def load_items_new(
+        self,
+        node_id: int,
+        filter_workspace_depth: int | None = None,
+        filter_workspace_subtypes: list | None = None,
+        filter_workspace_category: str | None = None,
+        filter_workspace_attributes: dict | list | None = None,
+        filter_item_depth: int | None = None,
+        filter_item_subtypes: list | None = None,
+        filter_item_category: str | None = None,
+        filter_item_attributes: dict | list | None = None,
+        filter_item_in_workspace: bool = True,
+        exclude_node_ids: list | None = None,
+        workspace_metadata: bool = True,
+        item_metadata: bool = True,
+        download_documents: bool = True,
+        skip_existing_downloads: bool = True,
+        extract_zip: bool = False,
+        workers: int = 3,
+    ) -> dict | None:
+        """Create a Pandas Data Frame by traversing a given Content Server hierarchy.
+
+        This method collects workspace and document items.
+
+        Args:
+            node_id (int):
+                The root Node ID the traversal should start at.
+            filter_workspace_depth (int | None, optional):
+                Additive filter criterium for workspace path depth.
+                Defaults to None = filter not active.
+            filter_workspace_subtypes (list | None, optional):
+                Additive filter criterium for workspace type.
+                Defaults to None = filter not active.
+            filter_workspace_category (str | None, optional):
+                Additive filter criterium for workspace category.
+                Defaults to None = filter not active.
+            filter_workspace_attributes (dict | list, optional):
+                Additive filter criterium for workspace attribute values.
+                Defaults to None = filter not active
+            filter_item_depth (int | None, optional):
+                Additive filter criterium for item path depth.
+                Defaults to None = filter not active.
+            filter_item_subtypes (list | None, optional):
+                Additive filter criterium for item types.
+                Defaults to None = filter not active.
+            filter_item_category (str | None, optional):
+                Additive filter criterium for item category.
+                Defaults to None = filter not active.
+            filter_item_attributes (dict | list, optional):
+                Additive filter criterium for item attribute values.
+                Defaults to None = filter not active.
+            filter_item_in_workspace (bool, optional):
+                Defines if item filters should be applied to
+                items inside workspaces as well. If False,
+                then items inside workspaces are always included.
+            exclude_node_ids (list, optional):
+                List of node IDs to exclude from traversal.
+            workspace_metadata (bool, optional):
+                If True, include workspace metadata.
+            item_metadata (bool, optional):
+                if True, include item metadata.
+            download_documents (bool, optional):
+                Whether or not documents should be downloaded.
+            skip_existing_downloads (bool, optional):
+                If True, reuse already existing downloads in the file system.
+            extract_zip (bool, optional):
+                If True, documents that are downloaded with mime-type
+                "application/x-zip-compressed" will be extracted recursively.
+            workers (int, optional):
+                Number of worker threads to start.
+
+        Returns:
+            dict:
+                Stats with processed and traversed counters.
+
+        """
+
+        # Initiaze download threads for this subnode:
+        download_threads = []
+
+        def check_node_exclusions(node: dict, **kwargs: dict) -> tuple[bool, bool]:
+            """Check if the processed node is on the exclusion list.
+
+            Stop processing and traversing if the node is excluded.
+
+            Args:
+                node (dict):
+                    The current node being processed.
+                kwargs (dict):
+                    Additional keyword arguments that are specific for the method.
+
+            Returns:
+                tuple[bool, bool]:
+                    success (bool) - if node was processed successfully
+                    traverse (bool) - if subnodes should be processed
+
+            """
+
+            exclude_node_ids = kwargs.get("exclude_node_ids")
+            if exclude_node_ids is None:
+                self.logger.error("Missing keyword arguments for executable in node traversal!")
+                return (False, False)
+
+            node_id = self.get_result_value(response=node, key="id")
+            node_name = self.get_result_value(response=node, key="name")
+
+            if node_id and exclude_node_ids is not None and (node_id in exclude_node_ids):
+                self.logger.info(
+                    "Node -> '%s' (%s) is in exclusion list. Skip traversal of this node.",
+                    node_name,
+                    node_id,
+                )
+                return (False, False)
+            return (True, True)
+
+        # end check_node_exclusions()
+
+        def check_node_workspace(node: dict, **kwargs: dict) -> tuple[bool, bool]:
+            """Check if the processed node should be recorded as a workspace in the data frame.
+
+            Args:
+                node (dict):
+                    The current node being processed.
+                kwargs (dict):
+                    Additional keyword arguments that are specific for the method.
+
+            Returns:
+                tuple[bool, bool]:
+                    success (bool) - if node was processed successfully
+                    traverse (bool) - if subnodes should be processed
+
+            """
+
+            traversal_data = kwargs.get("traversal_data")
+            filter_workspace_data = kwargs.get("filter_workspace_data")
+            control_flags = kwargs.get("control_flags")
+
+            if not traversal_data or not filter_workspace_data or not control_flags:
+                self.logger.error("Missing keyword arguments for executable in node traversal!")
+                return False
+
+            node_id = self.get_result_value(response=node, key="id")
+            node_name = self.get_result_value(response=node, key="name")
+            node_description = self.get_result_value(response=node, key="description")
+            node_type = self.get_result_value(response=node, key="type")
+
+            #
+            # 1. Check if the traversal is already inside a workflow. Then we can skip
+            #    the workspace processing. We currently don't support sub-workspaces.
+            #
+            workspace_id = traversal_data["workspace_id"]
+            if workspace_id:
+                self.logger.debug(
+                    "Found folder or workspace -> '%s' (%s) inside workspace with ID -> %s. So this container cannot be a workspace.",
+                    node_name,
+                    node_id,
+                    workspace_id,
+                )
+                # Success = False, Traverse = True
+                return (False, True)
+
+            #
+            # 2. Check if metadata is required (either for columns or for filters)
+            #
+            if (
+                control_flags["workspace_metadata"]
+                or filter_workspace_data["filter_workspace_category"]
+                or filter_workspace_data["filter_workspace_attributes"]
+            ):
+                categories = self.get_node_categories(
+                    node_id=node_id,
+                    metadata=(
+                        filter_workspace_data["filter_workspace_category"] is not None
+                        or filter_workspace_data["filter_workspace_attributes"] is not None
+                        or not self._use_numeric_category_identifier
+                    ),
+                )
+            else:
+                categories = None
+
+            #
+            # 3. Apply the defined filters to the current node to see
+            #    if we want to 'interpret' it as a workspace
+            #
+            # See if it is a node that we want to interpret as a workspace.
+            # Only "workspaces" that comply with ALL provided filters are
+            # considered and written into the data frame as a workspace row:
+            # Root nodes may have a "results" dict. The subnode iterators don't have it:
+            node_properties = node["results"]["data"]["properties"] if "results" in node else node["data"]["properties"]
+            if not self.apply_filter(
+                node=node_properties,
+                node_categories=categories,
+                current_depth=traversal_data["current_depth"],
+                filter_depth=filter_workspace_data["filter_workspace_depth"],
+                filter_subtypes=filter_workspace_data["filter_workspace_subtypes"],
+                filter_category=filter_workspace_data["filter_workspace_category"],
+                filter_attributes=filter_workspace_data["filter_workspace_attributes"],
+            ):
+                # Success = False, Traverse = True
+                return (False, True)
+
+            self.logger.debug(
+                "Found workspace -> '%s' (%s) in depth -> %s.",
+                node_name,
+                node_id,
+                traversal_data["current_depth"],
+            )
+
+            #
+            # 4. Create the data frame row from the node / traversal data:
+            #
+            row = {}
+            row["workspace_type"] = node_type
+            row["workspace_id"] = node_id
+            row["workspace_name"] = node_name
+            row["workspace_description"] = node_description
+            row["workspace_outer_path"] = traversal_data["folder_path"]
+            # If we want (and have) metadata then add it as columns:
+            if control_flags["workspace_metadata"] and categories and categories.get("results", None):
+                # Add columns for workspace node categories have been determined above.
+                self.add_attribute_columns(row=row, categories=categories, prefix="workspace_cat_")
+
+            # Now we add the article to the Pandas Data Frame in the Data class:
+            with self._data.lock():
+                self._data.append(row)
+
+            #
+            # 5. Update the traversal data:
+            #
+            traversal_data["workspace_id"] = node_id
+            traversal_data["workspace_name"] = node_name
+            traversal_data["workspace_type"] = node_type
+            traversal_data["workspace_description"] = node_description
+            self.logger.debug("Updated traversal data -> %s", str(traversal_data))
+
+            # Success = True, Traverse = False
+            # We have traverse = True because we need to
+            # keep traversing into the workspace folders.
+            return (True, True)
+
+        # end check_node_workspace()
+
+        def check_node_item(node: dict, **kwargs: dict) -> tuple[bool, bool]:
+            """Check if the processed node should be recorded as an item in the data frame.
+
+            Args:
+                node (dict):
+                    The current node being processed.
+                kwargs (dict):
+                    Additional keyword arguments that are specific for the method.
+
+            Returns:
+                tuple[bool, bool]:
+                    success (bool) - if node was processed successfully
+                    traverse (bool) - if subnodes should be processed
+
+            """
+
+            traversal_data = kwargs.get("traversal_data")
+            filter_item_data = kwargs.get("filter_item_data")
+            control_flags = kwargs.get("control_flags")
+
+            if not traversal_data or not filter_item_data or not control_flags:
+                self.logger.error("Missing keyword arguments for executable in node item traversal!")
+                return (False, False)
+
+            node_id = self.get_result_value(response=node, key="id")
+            node_name = self.get_result_value(response=node, key="name")
+            node_description = self.get_result_value(response=node, key="description")
+            node_type = self.get_result_value(response=node, key="type")
+
+            current_depth = traversal_data["current_depth"]
+            folder_path = traversal_data["folder_path"]
+            workspace_id = traversal_data["workspace_id"]
+            workspace_name = traversal_data["workspace_name"]
+            workspace_description = traversal_data["workspace_description"]
+            workspace_type = traversal_data["workspace_type"]
+
+            #
+            # 1. Check if metadata is required (either for columns or for filters)
+            #
+            if (
+                control_flags["item_metadata"]
+                or filter_item_data["filter_item_category"]
+                or filter_item_data["filter_item_attributes"]
+            ):
+                categories = self.get_node_categories(
+                    node_id=node_id,
+                    metadata=(
+                        filter_item_data["filter_item_category"] is not None
+                        or filter_item_data["filter_item_attributes"] is not None
+                        or not self._use_numeric_category_identifier
+                    ),
+                )
+            else:
+                categories = None
+
+            #
+            # 2. Apply the defined filters to the current node to see
+            #    if we want to add it to the data frame as an item.
+            #
+            # If filter_item_in_workspace is false, then documents
+            # inside workspaces are included in the data frame unconditionally!
+            # We apply the defined filters to the current node. Only "documents"
+            # that comply with ALL provided filters are considered and written into the data frame
+            node_properties = node["results"]["data"]["properties"] if "results" in node else node["data"]["properties"]
+            if (not workspace_id or filter_item_in_workspace) and not self.apply_filter(
+                node=node_properties,
+                node_categories=categories,
+                current_depth=current_depth,
+                filter_depth=filter_item_data["filter_item_depth"],
+                filter_subtypes=filter_item_data["filter_item_subtypes"],
+                filter_category=filter_item_data["filter_item_category"],
+                filter_attributes=filter_item_data["filter_item_attributes"],
+            ):
+                # Success = False, Traverse = True
+                return (False, True)
+
+            # We only consider documents that are inside the defined "workspaces":
+            if workspace_id:
+                self.logger.debug(
+                    "Found %s item -> '%s' (%s) in depth -> %s inside workspace -> '%s' (%s).",
+                    "document" if node_type == self.ITEM_TYPE_DOCUMENT else "URL",
+                    node_name,
+                    node_id,
+                    current_depth,
+                    workspace_name,
+                    workspace_id,
+                )
+            else:
+                self.logger.debug(
+                    "Found %s item -> '%s' (%s) in depth -> %s outside of workspace.",
+                    "document" if node_type == self.ITEM_TYPE_DOCUMENT else "URL",
+                    node_name,
+                    node_id,
+                    current_depth,
+                )
+
+            # Special handling for documents: download them if requested:
+            if node_type == self.ITEM_TYPE_DOCUMENT:
+                # We use the node ID as the filename to avoid any
+                # issues with too long or not valid file names.
+                # As the Pandas DataFrame has all information
+                # this is easy to resolve at upload time.
+                file_path = "{}/{}".format(self._download_dir, node_id)
+
+                # We download only if not downloaded before or if downloaded
+                # before but forced to re-download:
+                if control_flags["download_documents"] and (
+                    not os.path.exists(file_path) or not control_flags["skip_existing_downloads"]
+                ):
+                    #
+                    # Start anasynchronous Download Thread:
+                    #
+                    self.logger.debug(
+                        "Downloading file -> '%s'...",
+                        file_path,
+                    )
+
+                    extract_after_download = node["mime_type"] == "application/x-zip-compressed" and extract_zip
+                    thread = threading.Thread(
+                        target=self.download_document_multi_threading,
+                        args=(node_id, file_path, extract_after_download),
+                        name="download_document_node_{}".format(node_id),
+                    )
+                    thread.start()
+                    download_threads.append(thread)
+                else:
+                    self.logger.debug(
+                        "File -> %s has been downloaded before or download is not requested. Skipping download...",
+                        file_path,
+                    )
+            # end if document
+
+            #
+            # Construct a dictionary 'row' that we will add
+            # to the resulting data frame:
+            #
+            row = {}
+            # First we include some key workspace data to associate
+            # the item with the workspace:
+            row["workspace_type"] = workspace_type
+            row["workspace_id"] = workspace_id
+            row["workspace_name"] = workspace_name
+            row["workspace_description"] = workspace_description
+            # Then add item specific data:
+            row["item_id"] = str(node_id)
+            row["item_type"] = node_type
+            row["item_name"] = node_name
+            row["item_description"] = node_description
+            # We take the sub-path of the folder path inside the workspace
+            # as the item path:
+            try:
+                # Item path are the list elements after the item that is the workspace name:
+                row["item_path"] = folder_path[folder_path.index(workspace_name) + 1 :]
+            except ValueError:
+                self.logger.warning("Cannot access folder path while processing -> '%s' (%s)!", node_name, node_id)
+                row["item_path"] = []
+            row["item_download_name"] = str(node_id) if node_type == self.ITEM_TYPE_DOCUMENT else ""
+            row["item_mime_type"] = (
+                self.get_result_value(response=node, key="mime_type") if node_type == self.ITEM_TYPE_DOCUMENT else ""
+            )
+            # URL specific data:
+            row["item_url"] = (
+                self.get_result_value(response=node, key="mime_type") if node_type == self.ITEM_TYPE_URL else ""
+            )
+            if item_metadata and categories and categories["results"]:
+                # Add columns for workspace node categories have been determined above.
+                self.add_attribute_columns(row=row, categories=categories, prefix="item_cat_")
+
+            # Now we add the row to the Pandas Data Frame in the Data class:
+            self.logger.info(
+                "Adding %s -> '%s' (%s) to data frame...",
+                "document" if node_type == self.ITEM_TYPE_DOCUMENT else "URL",
+                row["item_name"],
+                row["item_id"],
+            )
+            with self._data.lock():
+                self._data.append(row)
+
+            return True
+
+        # end check_node_item()
+
+        #
+        # Start Main method:
+        #
+
+        # Create folder if it does not exist
+        if download_documents and not os.path.exists(self._download_dir):
+            os.makedirs(self._download_dir)
+
+        # These won't change during processing - stays the same for all nodes:
+        filter_workspace_data = {
+            "filter_workspace_depth": filter_workspace_depth,
+            "filter_workspace_subtypes": filter_workspace_subtypes,
+            "filter_workspace_category": filter_workspace_category,
+            "filter_workspace_attributes": filter_workspace_attributes,
+        }
+
+        # These won't change during processing - stays the same for all nodes:
+        filter_item_data = {
+            "filter_item_depth": filter_item_depth,
+            "filter_item_subtypes": filter_item_subtypes,
+            "filter_item_category": filter_item_category,
+            "filter_item_attributes": filter_item_attributes,
+            "filter_item_in_workspace": filter_item_in_workspace,
+        }
+
+        # These won't change during processing - stays the same for all nodes:
+        control_flags = {
+            "workspace_metadata": workspace_metadata,
+            "item_metadata": item_metadata,
+            "download_documents": download_documents,
+            "skip_existing_downloads": skip_existing_downloads,
+            "extract_zip": extract_zip,
+        }
+
+        #
+        # Start the traversal of the nodes:
+        #
+        result = self.traverse_node_parallel(
+            node=node_id,
+            executables=[check_node_exclusions, check_node_workspace, check_node_item],
+            exclude_node_ids=exclude_node_ids,
+            filter_workspace_data=filter_workspace_data,
+            filter_item_data=filter_item_data,
+            control_flags=control_flags,
+            workers=workers,
+        )
+
+        return result
+
+    # end method definition
+
     def aviator_embed_metadata(
         self,
         node_id: int,
@@ -15351,7 +17360,7 @@ class OTCS:
                 Defines if the method waits for the completion of the embedding. Defaults to True.
             message_override (dict | None, optional):
                 Overwrite specific message details. Defaults to None.
-            timeout (float):
+            timeout (float, optional):
                 Time in seconds to wait until the WebSocket times out. Defaults to 10.0.
             document_metadata (bool, optional):
                 Defines whether or not to embed document metadata.