pyxecm 2.0.1__py3-none-any.whl → 2.0.3__py3-none-any.whl

pyxecm/otcs.py

@@ -87,7 +87,7 @@ except ModuleNotFoundError:
 
 
 class OTCS:
-    """Used to automate stettings in OpenText Extended ECM."""
+    """Used to automate stettings in OpenText Content Management."""
 
     logger: logging.Logger = default_logger
 
@@ -148,6 +148,24 @@ class OTCS:
     ITEM_TYPE_WORKFLOW_MAP = 128
     ITEM_TYPE_WORKFLOW_STATUS = 190
 
+    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",
+    ]
     _config: dict
     _otcs_ticket = None
     _otds_ticket = None
@@ -858,6 +876,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:
@@ -1671,11 +1692,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 +1941,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",
@@ -2019,12 +2037,18 @@ class OTCS:
     # end method definition
 
     @cache
-    def get_user(self, name: str, show_error: bool = False) -> dict | None:
+    def get_user(self, name: str, user_type: int = 0, show_error: bool = False) -> dict | None:
         """Look up an Content Server user based on the login name.
 
         Args:
             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.
 
@@ -2082,8 +2106,8 @@ class OTCS:
         """
 
         # Add query parameters (these are NOT passed via JSon body!)
-        # type = 0 ==> User
-        query = {"where_type": 0, "where_name": name}
+        # type = 0 ==> regular 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)
 
@@ -2122,18 +2146,26 @@ class OTCS:
         """Add Content Server user.
 
         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)
+            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): id of user_type 0-User, 17-ServiceUser, ...
+            user_type (int, optional):
+                The ID of the user type. 0 = regular user, 17 = service user.
 
         Returns:
             dict | None:
@@ -2268,9 +2300,12 @@ class OTCS:
         """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:
@@ -3669,7 +3704,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 +3907,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 +4353,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 +4381,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 +4403,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 +4439,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 +4478,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 +4819,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.
 
         """
 
@@ -5044,6 +5007,285 @@ class OTCS:
 
     # 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
+
+        audit_size = response["collection"]["paging"]["total_count"]
+
+        # 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
+
+        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
+
     def get_volumes(self) -> dict | None:
         """Get all Volumes.
 
@@ -5123,11 +5365,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 +5656,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.
@@ -5972,13 +6217,16 @@ class OTCS:
         """Get document content from Extended ECM and read 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.
 
         """
 
@@ -6528,11 +6776,14 @@ class OTCS:
         """Get Extended ECM 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 +6821,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 +6842,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 +7050,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 +7280,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 +7428,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 +7673,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:
@@ -8393,11 +8647,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 +9467,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 +9501,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.
 
         """
 
@@ -9283,13 +9542,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 +9621,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 +9700,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 +9751,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 +9767,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 +9827,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.
 
         """
 
@@ -9878,12 +10160,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 +10253,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:
@@ -10327,7 +10609,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 +10666,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 +10688,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,
         )
@@ -10598,12 +10883,12 @@ 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,
@@ -10611,15 +10896,6 @@ class OTCS:
 
         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.
             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 +10907,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 +10932,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 +10967,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 +10984,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 +10996,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
                 ),
             )