[CDF-21402] Breaking change: data workflows cancel endpoint (#1742)

Only allow a single execution to be cancelled at a time, reflecting the endpoints' non-atomic workings.

CHANGELOG.md

@@ -17,6 +17,10 @@ Changes are grouped as follows
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+## [7.42.0] - 2024-05-06
+### Changed
+- Breaking change: the `workflows.executions.cancel` method now only allows cancelling one execution at a time to reflect its non-atomic operation.
+
 ## [7.41.1] - 2024-05-06
 ### Fixed
 - An edge case when a request for datapoints from several hundred time series (with specific finite limits) would return

cognite/client/_api/workflows.py

@@ -1,15 +1,14 @@
 from __future__ import annotations
 
 from abc import ABC
-from typing import TYPE_CHECKING, Any, Literal, MutableSequence, Sequence, Tuple, Union
+from typing import TYPE_CHECKING, Any, Literal, MutableSequence, Tuple, Union
 from urllib.parse import quote
 
 from typing_extensions import TypeAlias
 
 from cognite.client._api_client import APIClient
 from cognite.client._constants import DEFAULT_LIMIT_READ
 from cognite.client.data_classes.workflows import (
-    CancelExecution,
     Workflow,
     WorkflowExecution,
     WorkflowExecutionDetailed,
@@ -262,18 +261,19 @@ def list(
             limit=limit,
         )
 
-    def cancel(self, executions: Sequence[CancelExecution]) -> Sequence[WorkflowExecution]:
+    def cancel(self, id: str, reason: str | None) -> WorkflowExecution:
         """`cancel a workflow execution. <https://api-docs.cognite.com/20230101-beta/tag/Workflow-executions/operation/WorkflowExecutionCancellation>`_
 
         Args:
-            executions (Sequence[CancelExecution]): List of executions to cancel.
+            id (str): The server-generated id of the workflow execution.
+            reason (str | None): The reason for the cancellation, this will be put within the execution's `reasonForIncompletion` field. It is defaulted to 'cancelled' if not provided.
 
-        Tip:
-            Cancelling a workflow only prevents it from starting new tasks, tasks already running on
-            other services (transformations and functions) will keep running there.
+        Note:
+            Cancelling a workflow will immediately cancel the `in_progress` tasks, but not their spawned work in
+            other services (like transformations and functions).
 
         Returns:
-            Sequence[WorkflowExecution]: The canceled workflow executions.
+            WorkflowExecution: The canceled workflow execution.
 
         Examples:
 
@@ -283,15 +283,19 @@ def cancel(self, executions: Sequence[CancelExecution]) -> Sequence[WorkflowExec
                 >>> from cognite.client.data_classes import CancelExecution
                 >>> client = CogniteClient()
                 >>> res = client.workflows.executions.trigger("foo", "1")
-                >>> client.workflows.executions.cancel([CancelExecution(res.id, "test cancelation")])
+                >>> client.workflows.executions.cancel(id="foo", reason="test cancelation")
         """
         self._warning.warn()
         response = self._post(
-            url_path=f"{self._RESOURCE_PATH}/cancel",
-            json={"items": [execution.dump(camel_case=True) for execution in executions]},
+            url_path=f"{self._RESOURCE_PATH}/{id}/cancel",
+            json={
+                "reason": reason,
+            }
+            if reason
+            else {},
         )
 
-        return [WorkflowExecution._load(execution) for execution in response.json()["items"]]
+        return WorkflowExecution._load(response.json())
 
     def retry(self, id: str, client_credentials: ClientCredentials | None = None) -> WorkflowExecution:
         """`Retry a workflow execution. <https://api-docs.cognite.com/20230101-beta/tag/Workflow-executions/operation/WorkflowExecutionRetryn>`_
@@ -310,7 +314,7 @@ def retry(self, id: str, client_credentials: ClientCredentials | None = None) ->
                 >>> from cognite.client.data_classes import CancelExecution
                 >>> client = CogniteClient()
                 >>> res = client.workflows.executions.trigger("foo", "1")
-                >>> client.workflows.executions.cancel([CancelExecution(res.id, "test cancellation")])
+                >>> client.workflows.executions.cancel(id=res.id, reason="test cancellation")
                 >>> client.workflows.executions.retry(res.id)
         """
         self._warning.warn()

cognite/client/_version.py

@@ -1,4 +1,4 @@
 from __future__ import annotations
 
-__version__ = "7.41.1"
+__version__ = "7.42.0"
 __api_subversion__ = "20230101"

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "cognite-sdk"
 
-version = "7.41.1"
+version = "7.42.0"
 description = "Cognite Python SDK"
 readme = "README.md"
 documentation = "https://cognite-sdk-python.readthedocs-hosted.com"

tests/tests_integration/test_api/test_data_workflows.py

@@ -7,7 +7,6 @@
 from cognite.client import CogniteClient
 from cognite.client.data_classes import Function
 from cognite.client.data_classes.workflows import (
-    CancelExecution,
     CDFTaskParameters,
     FunctionTaskParameters,
     SubworkflowTaskParameters,
@@ -421,11 +420,9 @@ def test_trigger_cancel_retry_workflow(
             add_multiply_workflow.version,
         )
 
-        cancelled_workflow_executions = cognite_client.workflows.executions.cancel(
-            [CancelExecution(id=workflow_execution.id, reason="test")]
+        cancelled_workflow_execution = cognite_client.workflows.executions.cancel(
+            id=workflow_execution.id, reason="test"
         )
-        assert len(cancelled_workflow_executions) == 1
-        cancelled_workflow_execution = cancelled_workflow_executions[0]
         assert cancelled_workflow_execution.status == "terminated"
         assert cancelled_workflow_execution.reason_for_incompletion == "test"