feat: Execute work item API (#199)

Co-authored-by: Priyadarshini Piramanayagam <priydarshini.piramanayagam@emerson.com>
Co-authored-by: ShriramS-Emerson <shriram.sakthivel@emerson.com>

Author: 3 people

docs/api_reference/work_item.rst

@@ -13,6 +13,7 @@ nisystemlink.clients.work_item
    .. automethod:: update_work_items
    .. automethod:: schedule_work_items
    .. automethod:: delete_work_items
+   .. automethod:: execute_work_item
    .. automethod:: create_work_item_templates
    .. automethod:: query_work_item_templates
    .. automethod:: update_work_item_templates

docs/getting_started.rst

@@ -456,13 +456,13 @@ default connection. The default connection depends on your environment.
 
 With a :class:`.WorkItemClient` object, you can:
 
-* Create, query, get, update, schedule and delete work items
+* Create, query, get, update, schedule, delete and execute work items
 * Create, query, update and delete work item templates
 
 Examples
 ~~~~~~~~
 
-Create, query, get, update, schedule and delete work items
+Create, query, get, update, schedule, delete and execute work items
 
 .. literalinclude:: ../examples/work_item/work_items.py
    :language: python

examples/work_item/work_items.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 
 from nisystemlink.clients.core import HttpConfiguration
-from nisystemlink.clients.work_item import WorkItemClient
+from nisystemlink.clients.work_item import WorkItemClient, WorkItemExecuteApiException
 from nisystemlink.clients.work_item.models import (
     CreateWorkItemRequest,
     Dashboard,
@@ -105,6 +105,7 @@
         dashboard=Dashboard(
             id="DashboardId", variables={"product": "PXIe-4080", "location": "Lab1"}
         ),
+        workflow_id="example-workflow-id",
         execution_actions=[
             ManualExecution(action="boot", type="MANUAL"),
             JobExecution(
@@ -202,6 +203,28 @@
             f"Scheduled work item with ID: {schedule_work_items_response.scheduled_work_items[0].id}"
         )
 
+# Execute work item action
+if created_work_item_id is not None:
+    try:
+        execute_response = client.execute_work_item(
+            work_item_id=created_work_item_id, action="START"
+        )
+        if execute_response.result is not None:
+            print(f"Executed action successfully. Type: {execute_response.result.type}")
+
+            # Use type narrowing to access type-specific fields
+            if execute_response.result.type == "NOTEBOOK":
+                print(f"Notebook execution ID: {execute_response.result.execution_id}")
+            elif execute_response.result.type == "JOB":
+                if execute_response.result.job_ids:
+                    print(f"Job IDs: {', '.join(execute_response.result.job_ids)}")
+    except WorkItemExecuteApiException as e:
+        print(f"Execution failed (HTTP {e.http_status_code}): {e.error}")
+        if e.result is not None:
+            print(f"Partial result: {e.result.type}")
+    except Exception as e:
+        print(f"Could not execute action: {e}")
+
 # Delete work item
 if created_work_item_id is not None:
     client.delete_work_items(ids=[created_work_item_id])

nisystemlink/clients/core/_api_exception.py

@@ -3,6 +3,7 @@
 """Implementation of ApiException."""
 
 import typing
+from typing import Any, Dict
 
 from nisystemlink.clients import core
 
@@ -16,6 +17,7 @@ def __init__(
         error: core.ApiError | None = None,
         http_status_code: int | None = None,
         inner: Exception | None = None,
+        response_data: Dict[str, Any] | None = None,
     ) -> None:
         """Initialize an exception.
 
@@ -25,11 +27,14 @@ def __init__(
             http_status_code: The HTTP status code, if this exception was the result of
                 an HTTP error.
             inner: The inner exception that caused the error.
+            response_data: The full parsed JSON response body, if the server returned
+                one. Useful when an error response still contains actionable data.
         """
         self._message = message
         self._error = error
         self._http_status_code = http_status_code
         self._inner = inner
+        self._response_data = response_data
 
     @property
     def message(self) -> str | None:  # noqa:D401
@@ -56,6 +61,16 @@ def inner_exception(self) -> Exception | None:  # noqa: D401
         """The exception that caused this failure, if any."""
         return self._inner
 
+    @property
+    def response_data(self) -> Dict[str, Any] | None:  # noqa: D401
+        """The full parsed JSON response body returned by the server, or None.
+
+        This is populated for HTTP error responses that include a JSON body.
+        It allows callers to recover structured data from error responses — for
+        example, a partial-failure response may contain result data alongside the error details.
+        """
+        return dict(self._response_data) if self._response_data is not None else None
+
     def __str__(self) -> str:
         txt = self._message or "API exception occurred"
         if self._error:
@@ -71,6 +86,7 @@ def __eq__(self, other: object) -> bool:
                 self._error == other_._error,
                 self._http_status_code == other_._http_status_code,
                 self._inner == other_._inner,
+                self._response_data == other_._response_data,
             )
         )
 

nisystemlink/clients/core/_uplink/_base_client.py

@@ -34,7 +34,10 @@ def _handle_http_status(response: Response) -> Response | None:
             err_obj = None
 
         raise core.ApiException(
-            msg, error=err_obj, http_status_code=response.status_code
+            msg,
+            error=err_obj,
+            http_status_code=response.status_code,
+            response_data=content,
         )
     except JSONDecodeError:
         if response.text:

nisystemlink/clients/work_item/__init__.py

@@ -1,3 +1,3 @@
-from ._work_item_client import WorkItemClient
+from ._work_item_client import WorkItemClient, WorkItemExecuteApiException
 
 # flake8: noqa

nisystemlink/clients/work_item/_work_item_client.py

@@ -5,7 +5,31 @@
 from nisystemlink.clients.core._uplink._base_client import BaseClient
 from nisystemlink.clients.core._uplink._methods import get, post
 from nisystemlink.clients.work_item import models
-from uplink import Field, retry
+from uplink import Field, Path, retry
+
+
+class WorkItemExecuteApiException(core.ApiException):
+    """Raised when the execute work item API returns an error with a structured response body.
+
+    The API may return partial results (e.g. cancelled job IDs) alongside an error.
+    This exception exposes those results via the :attr:`result` property.
+    """
+
+    def __init__(
+        self,
+        msg: str,
+        *,
+        http_status_code: int,
+        error: core.ApiError | None,
+        result: models.ExecutionResult | None,
+    ) -> None:
+        super().__init__(msg, error=error, http_status_code=http_status_code)
+        self._result = result
+
+    @property
+    def result(self) -> models.ExecutionResult | None:
+        """The partial execution result returned alongside the error, if any."""
+        return self._result
 
 
 @retry(
@@ -132,6 +156,54 @@ def delete_work_items(
         """
         ...
 
+    def execute_work_item(
+        self, work_item_id: str, action: str
+    ) -> models.ExecuteWorkItemResponse:
+        """Executes the specified action for the work item.
+
+        Args:
+            work_item_id: The ID of the work item the action will be performed on.
+            action: The action to execute on the work item.
+
+        Returns:
+            The response containing the execution result.
+
+        Raises:
+            WorkItemExecuteApiException: if the API returns an error response with
+                an execute-specific body. The :attr:`~WorkItemExecuteApiException.result`
+                property may contain partial results (e.g. cancelled job IDs).
+            ApiException: if unable to communicate with the `/niworkitem` service
+                or provided invalid arguments.
+        """
+        try:
+            return self._execute_work_item(work_item_id=work_item_id, action=action)
+        except core.ApiException as e:
+            data = e.response_data
+            if not data or "result" not in data:
+                raise
+
+            try:
+                response = models.ExecuteWorkItemResponse.model_validate(data)
+            except Exception:
+                raise e
+
+            raise WorkItemExecuteApiException(
+                str(e),
+                http_status_code=e.http_status_code or 0,
+                error=response.error,
+                result=response.result,
+            ) from e
+
+    @post(
+        "workitems/{workItemId}/execute",
+        args=[Path(name="workItemId"), Field("action")],
+    )
+    def _execute_work_item(
+        self, work_item_id: str, action: str
+    ) -> models.ExecuteWorkItemResponse:
+        """Internal implementation of execute_work_item."""
+        ...
+
     @post("workitem-templates", args=[Field("workItemTemplates")])
     def create_work_item_templates(
         self, work_item_templates: List[models.CreateWorkItemTemplateRequest]

nisystemlink/clients/work_item/models/__init__.py

@@ -58,6 +58,18 @@
 )
 from ._update_work_items_request import UpdateWorkItemsRequest
 
+from ._execute_work_item_response import (
+    ExecuteWorkItemResponse,
+    ExecutionResult,
+    ExecutionResultBase,
+    JobExecutionResult,
+    ManualExecutionResult,
+    NoneExecutionResult,
+    NotebookExecutionResult,
+    ScheduleExecutionResult,
+    UnscheduleExecutionResult,
+)
+
 from ._create_work_item_template_request import CreateWorkItemTemplateRequest
 from ._create_work_item_templates_partial_success_response import (
     CreateWorkItemTemplatesPartialSuccessResponse,

nisystemlink/clients/work_item/models/_execute_work_item_response.py

@@ -0,0 +1,82 @@
+from typing import Annotated, List, Literal
+
+from nisystemlink.clients.core._api_error import ApiError
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+from pydantic import Field
+
+
+class ExecutionResultBase(JsonModel):
+    """Base class for execution results containing common attributes."""
+
+    error: ApiError | None = None
+    """Error information if the execution encountered an error."""
+
+
+class NoneExecutionResult(ExecutionResultBase):
+    """Result of executing a work item action with no execution implementation."""
+
+    type: Literal["NONE"] = Field(default="NONE")
+    """Type of execution."""
+
+
+class ManualExecutionResult(ExecutionResultBase):
+    """Result of executing a manual work item action."""
+
+    type: Literal["MANUAL"] = Field(default="MANUAL")
+    """Type of execution."""
+
+
+class NotebookExecutionResult(ExecutionResultBase):
+    """Result of executing a notebook work item action."""
+
+    type: Literal["NOTEBOOK"] = Field(default="NOTEBOOK")
+    """Type of execution."""
+
+    execution_id: str | None = None
+    """The notebook execution ID."""
+
+
+class JobExecutionResult(ExecutionResultBase):
+    """Result of executing a job work item action."""
+
+    type: Literal["JOB"] = Field(default="JOB")
+    """Type of execution."""
+
+    job_ids: List[str] | None = None
+    """The list of job IDs."""
+
+
+class ScheduleExecutionResult(ExecutionResultBase):
+    """Result of executing a schedule work item action."""
+
+    type: Literal["SCHEDULE"] = Field(default="SCHEDULE")
+    """Type of execution."""
+
+
+class UnscheduleExecutionResult(ExecutionResultBase):
+    """Result of executing an unschedule work item action."""
+
+    type: Literal["UNSCHEDULE"] = Field(default="UNSCHEDULE")
+    """Type of execution."""
+
+
+ExecutionResult = Annotated[
+    NoneExecutionResult
+    | ManualExecutionResult
+    | NotebookExecutionResult
+    | JobExecutionResult
+    | ScheduleExecutionResult
+    | UnscheduleExecutionResult,
+    Field(discriminator="type"),
+]
+"""Result of executing a work item action."""
+
+
+class ExecuteWorkItemResponse(JsonModel):
+    """Response for executing a work item action."""
+
+    error: ApiError | None = None
+    """Error information if the action failed."""
+
+    result: ExecutionResult | None = None
+    """Result of the action execution."""