feat(action-center): extend taskSourceMetadata on CreateTask/CreateEscalation

packages/uipath-platform/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-platform"
-version = "0.2.23"
+version = "0.2.24"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath-platform/src/uipath/platform/action_center/_tasks_service.py

@@ -44,19 +44,20 @@
 
 
 def _create_spec(
     data: Optional[Dict[str, Any]],
     action_schema: Optional[TaskSchema],
     title: str,
     app_key: Optional[str] = None,
     app_name: Optional[str] = None,
     app_folder_key: Optional[str] = None,
     app_folder_path: Optional[str] = None,
     priority: Optional[str] = None,
     labels: Optional[List[str]] = None,
     is_actionable_message_enabled: Optional[bool] = None,
     actionable_message_metadata: Optional[Dict[str, Any]] = None,
+    task_source_metadata: Optional[Dict[str, Any]] = None,
     source_name: str = "Agent",
     is_debug: bool = False,
 ) -> RequestSpec:
     field_list = []
     outcome_list = []
@@ -147,7 +148,12 @@
     _apply_priority_labels_and_actionable_toggle(
         json_payload, priority, labels, is_actionable_message_enabled
     )
-    _apply_task_source(json_payload, source_name, is_debug=is_debug)
+    _apply_task_source(
+        json_payload,
+        source_name,
+        is_debug=is_debug,
+        custom_metadata=task_source_metadata,
+    )
 
     return RequestSpec(
         method="POST",
@@ -185,12 +191,20 @@
 
 
 def _apply_task_source(
-    payload: Dict[str, Any], source_name: str, is_debug: bool = False
+    payload: Dict[str, Any],
+    source_name: str,
+    is_debug: bool = False,
+    custom_metadata: Optional[Dict[str, Any]] = None,
 ) -> None:
     """Populate ``payload["taskSource"]`` when UiPathConfig has project_id + trace_id.
 
     Shared between AppTask and QuickForm spec builders — the taskSource block is
     identical for both task types.
+
+    ``custom_metadata`` is merged into ``taskSourceMetadata`` on top of the built-in
+    InstanceId/FolderKey/JobKey/ProcessKey keys, so a caller-supplied key (e.g. a
+    conversational-agent id a HITL task should carry) wins on collision rather than
+    being silently dropped.
     """
     project_id = UiPathConfig.project_id
     trace_id = UiPathConfig.trace_id
@@ -204,6 +218,7 @@
             "FolderKey": UiPathConfig.folder_key,
             "JobKey": UiPathConfig.job_key,
             "ProcessKey": UiPathConfig.process_uuid,
+            **(custom_metadata or {}),
         },
         "jobId": UiPathConfig.job_key,
     }
@@ -474,21 +489,22 @@
     )
     @traced(name="tasks_create", run_type="uipath")
     async def create_async(
         self,
         title: str,
         data: Optional[Dict[str, Any]] = None,
         *,
         app_name: Optional[str] = None,
         app_key: Optional[str] = None,
         app_folder_path: Optional[str] = None,
         app_folder_key: Optional[str] = None,
         assignee: Optional[str] = None,
         recipient: Optional[TaskRecipient] = None,
         priority: Optional[str] = None,
         labels: Optional[List[str]] = None,
         is_actionable_message_enabled: Optional[bool] = None,
         actionable_message_metadata: Optional[Dict[str, Any]] = None,
+        task_source_metadata: Optional[Dict[str, Any]] = None,
         source_name: str = "Agent",
     ) -> Task:
         """Creates a new action asynchronously.
 
@@ -507,6 +523,9 @@
             labels: Optional list of labels for the task
             is_actionable_message_enabled: Optional boolean indicating whether actionable notifications are enabled for this task
             actionable_message_metadata: Optional metadata for the action
+            task_source_metadata: Optional extra keys merged into taskSource.taskSourceMetadata,
+                on top of the built-in InstanceId/FolderKey/JobKey/ProcessKey (e.g. a
+                conversational-agent id a HITL task should carry downstream)
             source_name: The name of the source that created the task. Defaults to 'Agent'.
 
         Returns:
@@ -540,6 +559,7 @@
             labels=labels,
             is_actionable_message_enabled=is_actionable_message_enabled,
             actionable_message_metadata=actionable_message_metadata,
+            task_source_metadata=task_source_metadata,
             source_name=source_name,
             is_debug=is_debug,
         )
@@ -568,21 +588,22 @@
     )
     @traced(name="tasks_create", run_type="uipath")
     def create(
         self,
         title: str,
         data: Optional[Dict[str, Any]] = None,
         *,
         app_name: Optional[str] = None,
         app_key: Optional[str] = None,
         app_folder_path: Optional[str] = None,
         app_folder_key: Optional[str] = None,
         assignee: Optional[str] = None,
         recipient: Optional[TaskRecipient] = None,
         priority: Optional[str] = None,
         labels: Optional[List[str]] = None,
         is_actionable_message_enabled: Optional[bool] = None,
         actionable_message_metadata: Optional[Dict[str, Any]] = None,
+        task_source_metadata: Optional[Dict[str, Any]] = None,
         source_name: str = "Agent",
     ) -> Task:
         """Creates a new task synchronously.
 
@@ -601,6 +622,9 @@
             labels: Optional list of labels for the task
             is_actionable_message_enabled: Optional boolean indicating  whether actionable notifications are enabled for this task
             actionable_message_metadata: Optional metadata for the action
+            task_source_metadata: Optional extra keys merged into taskSource.taskSourceMetadata,
+                on top of the built-in InstanceId/FolderKey/JobKey/ProcessKey (e.g. a
+                conversational-agent id a HITL task should carry downstream)
             source_name: The name of the source that created the task. Defaults to 'Agent'.
 
         Returns:
@@ -634,6 +658,7 @@
             labels=labels,
             is_actionable_message_enabled=is_actionable_message_enabled,
             actionable_message_metadata=actionable_message_metadata,
+            task_source_metadata=task_source_metadata,
             source_name=source_name,
             is_debug=is_debug,
         )

packages/uipath-platform/src/uipath/platform/common/interrupt_models.py

@@ -73,6 +73,7 @@ class CreateTask(BaseModel):
     labels: list[str] | None = None
     is_actionable_message_enabled: bool | None = None
     actionable_message_metadata: dict[str, Any] | None = None
+    task_source_metadata: dict[str, Any] | None = None
     source_name: str = "Agent"
 
 

packages/uipath-platform/src/uipath/platform/resume_triggers/_protocol.py

@@ -679,6 +679,7 @@ async def _handle_task_trigger(
                 labels=value.labels,
                 is_actionable_message_enabled=value.is_actionable_message_enabled,
                 actionable_message_metadata=value.actionable_message_metadata,
+                task_source_metadata=value.task_source_metadata,
                 source_name=value.source_name,
             )
             if not action:

packages/uipath-platform/tests/services/test_actions_service.py

@@ -1024,3 +1024,65 @@ def test_create_skips_jit_when_not_a_studio_project(
 
     assert _requested_app_schemas(httpx_mock)
     assert _posted_body(httpx_mock, create_task_url)["folderPath"] == "Shared/Apps"
+
+
+def test_create_merges_task_source_metadata(
+    httpx_mock: HTTPXMock,
+    service: TasksService,
+    create_task_url: str,
+    jit_debug_env: None,
+) -> None:
+    _mock_create_task(httpx_mock, create_task_url)
+
+    service.create(
+        title="Test Action",
+        app_key="test-app-key",
+        data={"test": "data"},
+        task_source_metadata={"ConversationalAgentId": "agent-1"},
+    )
+
+    task_source_metadata = _posted_body(httpx_mock, create_task_url)["taskSource"][
+        "taskSourceMetadata"
+    ]
+    assert task_source_metadata["ConversationalAgentId"] == "agent-1"
+    # The built-in correlation keys are still populated alongside the extra one.
+    assert task_source_metadata["InstanceId"] == "trace-1"
+
+
+async def test_create_async_merges_task_source_metadata(
+    httpx_mock: HTTPXMock,
+    service: TasksService,
+    create_task_url: str,
+    jit_debug_env: None,
+) -> None:
+    _mock_create_task(httpx_mock, create_task_url)
+
+    await service.create_async(
+        title="Test Action",
+        app_key="test-app-key",
+        data={"test": "data"},
+        task_source_metadata={"ConversationalAgentId": "agent-1"},
+    )
+
+    task_source_metadata = _posted_body(httpx_mock, create_task_url)["taskSource"][
+        "taskSourceMetadata"
+    ]
+    assert task_source_metadata["ConversationalAgentId"] == "agent-1"
+    assert task_source_metadata["InstanceId"] == "trace-1"
+
+
+def test_create_omits_extra_task_source_metadata_when_unset(
+    httpx_mock: HTTPXMock,
+    service: TasksService,
+    create_task_url: str,
+    jit_debug_env: None,
+) -> None:
+    _mock_create_task(httpx_mock, create_task_url)
+
+    service.create(title="Test Action", app_key="test-app-key", data={"test": "data"})
+
+    task_source_metadata = _posted_body(httpx_mock, create_task_url)["taskSource"][
+        "taskSourceMetadata"
+    ]
+    assert "ConversationalAgentId" not in task_source_metadata
+    assert task_source_metadata["InstanceId"] == "trace-1"

packages/uipath-platform/tests/services/test_hitl.py

@@ -1278,6 +1278,7 @@ async def test_create_resume_trigger_create_task(
                 labels=None,
                 is_actionable_message_enabled=None,
                 actionable_message_metadata=None,
+                task_source_metadata=None,
                 source_name="Agent",
             )