pyxecm 3.4.3__tar.gz → 3.4.5__tar.gz

{pyxecm-3.4.3 → pyxecm-3.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyxecm
-Version: 3.4.3
+Version: 3.4.5
 Summary: A Python library to interact with Opentext Content Management Rest API
 Project-URL: Homepage, https://github.com/opentext/pyxecm
 Author-email: Kai Gatzweiler <kgatzweiler@opentext.com>, "Dr. Marc Diefenbruch" <mdiefenb@opentext.com>

{pyxecm-3.4.3 → pyxecm-3.4.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyxecm"
-version = "3.4.3"
+version = "3.4.5"
 description = 'A Python library to interact with Opentext Content Management Rest API'
 keywords = [
   'opentext',

{pyxecm-3.4.3 → pyxecm-3.4.5}/src/pyxecm/otcs.py

@@ -542,6 +542,8 @@ class OTCS:
         otcs_config["businessObjectTypesUrl"] = otcs_rest_url + "/v2/businessobjecttypes"
         otcs_config["businessObjectsSearchUrl"] = otcs_rest_url + "/v2/forms/businessobjects/search"
         otcs_config["businessWorkspaceTypesUrl"] = otcs_rest_url + "/v1/businessworkspacetypes"
+        otcs_config["businessWorkspaceReportsUrl"] = otcs_rest_url + "/v2/businessworkspace"
+        otcs_config["businessWorkspaceMyTeamTodoUrl"] = otcs_rest_url + "/v2/businessworkspace/myteamtodo"
         otcs_config["businessWorkspaceTypesUrlv2"] = otcs_rest_url + "/v2/businessworkspacetypes"
         otcs_config["businessworkspacecreateform"] = otcs_rest_url + "/v2/forms/businessworkspaces/create"
         otcs_config["businessWorkspacesUrl"] = otcs_rest_url + "/v2/businessworkspaces"
@@ -608,6 +610,12 @@ class OTCS:
         self._soap_docman_client: Client | None = None
         self._soap_transport: Transport | None = None
 
+        # Memoized full reminder client/type list (client_id=None). Reminder client
+        # and type configuration is effectively static for the lifetime of an OTCS
+        # object, so caching it avoids repeated 1+N REST round-trips when a single
+        # add/update operation resolves and validates a reminder type multiple times.
+        self._reminder_clients_cache: list[dict] | None = None
+
         # Handle concurrent HTTP requests that may run into 401 errors and
         # re-authentication at the same time:
         self._authentication_lock = threading.Lock()
@@ -8520,6 +8528,9 @@ class OTCS:
                     str(volume_type),
                 )
 
+        if not mime_type:
+            mime_type = "application/octet-stream"  # Default to binary stream if mime type cannot be determined
+
         upload_post_files = [("file", (f"{file_name}", file_content, mime_type))]
 
         request_url = self.config()["nodesUrlv2"]
@@ -8811,6 +8822,9 @@ class OTCS:
                     parent_id,
                 )
 
+        if not mime_type:
+            mime_type = "application/octet-stream"  # Default to binary stream if mime type cannot be determined
+
         upload_post_files = [("file", (f"{file_name}", file_content, mime_type))]
 
         request_url = self.config()["nodesUrlv2"]
@@ -9179,6 +9193,9 @@ class OTCS:
                     node_id,
                 )
 
+        if not mime_type:
+            mime_type = "application/octet-stream"  # Default to binary stream if mime type cannot be determined
+
         upload_post_files = [("file", (f"{file_name}", file_content, mime_type))]
 
         request_url = self.config()["nodesUrlv2"] + "/" + str(node_id) + "/versions"
@@ -13530,16 +13547,22 @@ class OTCS:
     # end method definition
 
     @tracer.start_as_current_span(attributes=OTEL_TRACING_ATTRIBUTES, name="get_workspace_type_name")
-    def get_workspace_type_name(self, type_id: int) -> str | None:
+    def get_workspace_type_name(self, type_id: int, renew: bool = False) -> str | None:
         """Get the name of a workspace type based on the provided workspace type ID.
 
         The name is taken from a OTCS object variable self._workspace_type_lookup if recorded there.
-        If not yet derived it is determined via the REST API and then stored
-        in self._workspace_type_lookup (as a lookup cache).
+        If not yet derived - or if renew is requested - it is determined via the REST API and
+        then stored in self._workspace_type_lookup (as a lookup cache).
 
         Args:
             type_id (int):
                 The workspace type ID.
+            renew (bool, optional):
+                Whether to bypass the cache and force a fresh lookup via the REST API,
+                updating the cache entry. Useful for callers that cannot tolerate a
+                workspace type having been renamed/reconfigured since it was last cached
+                (self._workspace_type_lookup has no expiry and is shared across calls
+                for the lifetime of this OTCS instance).
 
         Returns:
             str | None:
@@ -13553,7 +13576,7 @@ class OTCS:
         """
 
         workspace_type = self._workspace_type_lookup.get(type_id)
-        if workspace_type:
+        if workspace_type and not renew:
             return workspace_type.get("name")
 
         workspace_type = self.get_workspace_type(type_id=type_id)
@@ -14931,7 +14954,7 @@ class OTCS:
     def create_workspace(
         self,
         workspace_template_id: int,
-        workspace_name: str,
+        workspace_name: str | None,
         workspace_description: str,
         workspace_type: int,
         category_data: dict | None = None,
@@ -14951,12 +14974,13 @@ class OTCS:
         template and type, with optional category data and business object details.
         It also supports linking to external systems and specifying metadata such as
         creation and modification dates.
+        If the name is not specified it will be derived from workspace metadata.
 
         Args:
             workspace_template_id (int):
                 The ID of the workspace template to be used.
-            workspace_name (str):
-                The name of the new workspace.
+            workspace_name (str | None):
+                The name of the new workspace. If not specified, it will be derived from workspace metadata.
             workspace_description (str):
                 A description of the new workspace.
             workspace_type (int):
@@ -15024,13 +15048,16 @@ class OTCS:
 
         create_workspace_post_data = {
             "template_id": str(workspace_template_id),
-            "name": workspace_name,
             "description": workspace_description,
             "wksp_type_id": str(workspace_type),
             "type": str(self.ITEM_TYPE_BUSINESS_WORKSPACE),
             "roles": {},  # category_data,
         }
 
+        # Yes, workspace name is optional. If not specified, it will be derived from workspace metadata.
+        if workspace_name:
+            create_workspace_post_data["name"] = workspace_name
+
         if category_data:
             create_workspace_post_data["roles"]["categories"] = category_data
         if external_create_date:
@@ -15062,7 +15089,7 @@ class OTCS:
         if parent_id is not None:
             create_workspace_post_data["parent_id"] = parent_id
             self.logger.debug(
-                "Use specified location with node ID -> %d for workspace -> '%s'",
+                "Use specified location with node ID -> %d for creation of workspace -> '%s'",
                 parent_id,
                 workspace_name,
             )
@@ -15211,7 +15238,7 @@ class OTCS:
         self,
         workspace_id: int,
         related_workspace_id: int,
-        relationship_type: str = "child",
+        relationship_type: str | None = "child",
         show_error: bool = True,
     ) -> dict | None:
         """Create a relationship between two workspaces.
@@ -15231,7 +15258,7 @@ class OTCS:
         and the other of type 'child', but this is a less common use case.
 
         Adding a relationship R1: A --> Child --> B makes A to the parent of B _AND_ also
-        B to the child of A. Requesting the childs of A will include edge R1. Requesting the
+        B to the child of A. Requesting the childs of A will include relationship R1. Requesting the
         parents of B will include R1 as well. But it is still possible to add a relationship
         R2: A --> Parent --> B. This will be a separate relationship.
 
@@ -15240,8 +15267,10 @@ class OTCS:
                 The ID of the workspace.
             related_workspace_id (int):
                 The ID of the related workspace.
-            relationship_type (str, optional):
-                Can be "parent" or "child" - "child" is default if not provided.
+            relationship_type (str | None, optional):
+                Can be "parent" or "child" - "child" is the default. If None (or empty)
+                is provided, it falls back to "child" instead of sending an invalid
+                relationship type to the REST API.
             show_error (bool, optional):
                 If True, log an error if relationship cration fails.
                 Otherwise log a warning.
@@ -15252,6 +15281,17 @@ class OTCS:
 
         """
 
+        # Normalize the relationship type so that callers passing None explicitly
+        # (which overrides the default) still get the intended "child" behavior:
+        if not relationship_type:
+            relationship_type = "child"
+        elif relationship_type not in ("parent", "child"):
+            self.logger.error(
+                "Illegal relationship type -> '%s'! Must be either 'parent' or 'child'.",
+                relationship_type,
+            )
+            return None
+
         create_workspace_relationship_post_data = {
             "rel_bw_id": str(related_workspace_id),
             "rel_type": relationship_type,
@@ -23961,6 +24001,12 @@ class OTCS:
         for workspace_type in workspace_types:
             wksp_type_id = self.get_result_value(response=workspace_type, key="wksp_type_id")
             wksp_type_name = self.get_result_value(response=workspace_type, key="wksp_type_name")
+            # Refresh the shared lookup cache with the current name (see the equivalent
+            # refresh in traverse_workspaces_parallel's init_traversal_queue for why this
+            # must overwrite rather than only fill in missing entries): this keeps
+            # get_workspace_type_name() calls made later in this traversal (e.g. from
+            # traverse_workspace()) from resolving a stale, previously-cached name.
+            self._workspace_type_lookup[wksp_type_id] = {"location": None, "name": wksp_type_name}
             if not self._check_filter(
                 workspace_type_name=wksp_type_name,
                 workspace_type_id=wksp_type_id,
@@ -24310,8 +24356,14 @@ class OTCS:
             for workspace_type in workspace_types:
                 wksp_type_id = self.get_result_value(response=workspace_type, key="wksp_type_id")
                 wksp_type_name = self.get_result_value(response=workspace_type, key="wksp_type_name")
-                if wksp_type_id not in self._workspace_type_lookup:
-                    self._workspace_type_lookup[wksp_type_id] = {"location": None, "name": wksp_type_name}
+                # Refresh (not just fill-if-missing): this is a fresh, current listing of
+                # workspace types, fetched on every traversal run. self._workspace_type_lookup
+                # is a long-lived cache on this OTCS instance (spans many traversal runs over the
+                # life of the process), so if we only filled in missing entries, a renamed
+                # workspace type would keep resolving to its stale old name here - and via
+                # get_workspace_type_name() - forever. Overwriting is free since we already have
+                # the current name from this iteration; no extra API call is needed.
+                self._workspace_type_lookup[wksp_type_id] = {"location": None, "name": wksp_type_name}
                 if not self._check_filter(
                     workspace_type_name=wksp_type_name,
                     workspace_type_id=wksp_type_id,
@@ -26113,6 +26165,14 @@ class OTCS:
 
         # end method definition of _extract_field_mappings()
 
+        # Serve the memoized full client/type list when no specific client filter
+        # is requested (the common case for type resolution and validation). The
+        # local `client_id` is reassigned inside the loop below, so capture the
+        # original intent up front for both the cache read and the cache write:
+        is_full_list = client_id is None
+        if is_full_list and self._reminder_clients_cache is not None:
+            return self._reminder_clients_cache
+
         response = self.get_reminder_types(client_id=client_id)
         if not response:
             return None
@@ -26154,6 +26214,10 @@ class OTCS:
             str(clients),
         )
 
+        # Memoize the full client/type list for subsequent lookups in this session:
+        if is_full_list:
+            self._reminder_clients_cache = clients
+
         return clients
 
     # end method definition
@@ -27501,7 +27565,13 @@ class OTCS:
             dict | None:
                 Response from the server, or None if the request fails.
 
-        Example:
+        Note:
+            On OTCM 26.2 and newer the `results` payload contains the ID of the
+            newly created reminder (extractable via `get_result_value(response, key="id")`).
+            On older releases `results` was empty even on success, so callers that
+            need the reminder ID on those releases must fall back to `get_reminders()`.
+
+        Example (OTCM 26.2 and newer):
         {
             'links': {
                 'data': {
@@ -27514,7 +27584,7 @@ class OTCS:
                     }
                 }
             },
-            'results': {} # seems to be always empty - also on success
+            'results': {'id': 66}  # ID of the newly created reminder (empty {} on releases before 26.2)
         }
 
         """
@@ -27890,3 +27960,170 @@ class OTCS:
         )
 
     # end method definition
+
+    @tracer.start_as_current_span(attributes=OTEL_TRACING_ATTRIBUTES, name="get_workspace_report_detail")
+    def get_workspace_report_detail(
+        self,
+        workspace_id: int,
+        report_type: str,
+    ) -> dict | None:
+        """Get the full document list for a single workspace report type.
+
+        REST operation: GET /v2/businessworkspace/{workspace_id}/reports?type={report_type}
+
+        Args:
+            workspace_id (int):
+                Business workspace node ID.
+            report_type (str):
+                Report type key. One of ``"documentsAdded"``, ``"outdatedDocuments"``,
+                or ``"recentDocuments"``.
+
+        Returns:
+            dict | None:
+                Report detail response containing a ``results.data`` list and
+                ``results.total_count``, or None on error.
+
+        """
+
+        request_url = "{}/{}/reports?type={}".format(
+            self.config()["businessWorkspaceReportsUrl"],
+            workspace_id,
+            report_type,
+        )
+        request_header = self.request_json_header()
+
+        self.logger.debug(
+            "Get workspace report detail for workspace with ID -> %d, type -> %s; calling -> %s",
+            workspace_id,
+            report_type,
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=REQUEST_TIMEOUT,
+            failure_message="Failed to get '{}' report detail for workspace with ID -> {}".format(
+                report_type, workspace_id
+            ),
+        )
+
+    # end method definition
+
+    @tracer.start_as_current_span(attributes=OTEL_TRACING_ATTRIBUTES, name="get_workspace_documents")
+    def get_workspace_documents(
+        self,
+        workspace_id: int,
+        document_type: Literal["missing", "inprocess"] = "missing",
+    ) -> dict | None:
+        """Get the list of missing or in-process documents for a Business Workspace.
+
+        REST operation: GET /v2/businessworkspaces/{workspace_id}/missingdocuments
+        REST operation: GET /v2/businessworkspaces/{workspace_id}/inprocessdocuments
+
+        Missing documents are required document types that are absent from the workspace.
+        In-process documents are currently being processed within the workspace
+        (e.g. pending classification, approval, or ingestion workflows).
+
+        Args:
+            workspace_id (int):
+                Business workspace node ID.
+            document_type (Literal["missing", "inprocess"], optional):
+                Which document category to retrieve:
+                * ``"missing"`` — required documents absent from the workspace
+                  (``/missingdocuments``).
+                * ``"inprocess"`` — documents currently being processed
+                  (``/inprocessdocuments``).
+                Defaults to ``"missing"``.
+
+        Returns:
+            dict | None:
+                Response containing a ``results.data`` list and ``results.total_count``,
+                or None on error.
+
+        """
+
+        endpoint = "inprocessdocuments" if document_type == "inprocess" else "missingdocuments"
+        request_url = "{}/{}/{}".format(
+            self.config()["businessWorkspacesUrl"],
+            workspace_id,
+            endpoint,
+        )
+        request_header = self.request_json_header()
+
+        self.logger.debug(
+            "Get %s for workspace with ID -> %d; calling -> %s",
+            endpoint,
+            workspace_id,
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=REQUEST_TIMEOUT,
+            failure_message="Failed to get {} for workspace with ID -> {}".format(endpoint, workspace_id),
+        )
+
+    # end method definition
+
+    @tracer.start_as_current_span(attributes=OTEL_TRACING_ATTRIBUTES, name="get_workspace_myteamtodo")
+    def get_workspace_myteamtodo(self) -> dict | None:
+        """Get the My Team Todo data for the currently authenticated user.
+
+        Returns the employee-file completeness status (missing and outdated document types)
+        for all direct reports of the currently authenticated user.
+
+        REST operation: GET /v2/businessworkspace/myteamtodo
+
+        Returns:
+            dict | None:
+                Response containing a ``results`` list where each element holds a
+                ``data.members`` list of direct reportees with their completeness status,
+                or None on error.
+
+        Example:
+                {
+                    'results': [
+                        {
+                            'data': {
+                                'members': [
+                                    {
+                                        'id': 1234,
+                                        'display_name': 'Ian Grant',
+                                        'first_name': 'Ian',
+                                        'last_name': 'Grant',
+                                        'business_email': 'ian.grant@example.com',
+                                        'employee_file_todos': {
+                                            'missing': [{'doc_type_name': 'Contract'}],
+                                            'outdated': [{'doc_type_name': 'Accident'}],
+                                        },
+                                    }
+                                ]
+                            },
+                            'properties': None,
+                        }
+                    ]
+                }
+
+        """
+
+        request_url = self.config()["businessWorkspaceMyTeamTodoUrl"]
+        request_header = self.request_json_header()
+
+        self.logger.debug(
+            "Get My Team Todo data for current user; calling -> %s",
+            request_url,
+        )
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=REQUEST_TIMEOUT,
+            failure_message="Failed to get My Team Todo data.",
+        )
+
+    # end method definition