feat: create virtual resources on push when catalog lookup misses (#1584)

Author: radu-mocanu

packages/uipath-platform/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-platform"
-version = "0.1.34"
+version = "0.1.35"
 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/resource_catalog/_resource_catalog_service.py

@@ -1,4 +1,4 @@
-from typing import Any, AsyncIterator, Dict, Iterator, List, Optional
+from typing import Any, AsyncGenerator, Dict, Iterator, List, Optional
 
 from uipath.core.tracing import traced
 
@@ -110,7 +110,7 @@ async def search_async(
         resource_types: Optional[List[ResourceType]] = None,
         resource_sub_types: Optional[List[str]] = None,
         page_size: int = _DEFAULT_PAGE_SIZE,
-    ) -> AsyncIterator[Resource]:
+    ) -> AsyncGenerator[Resource, None]:
         """Asynchronously search for tenant scoped resources and folder scoped resources (accessible to the user).
 
         This method automatically handles pagination and yields resources one by one.
@@ -258,7 +258,7 @@ async def list_async(
         folder_path: Optional[str] = None,
         folder_key: Optional[str] = None,
         page_size: int = _DEFAULT_PAGE_SIZE,
-    ) -> AsyncIterator[Resource]:
+    ) -> AsyncGenerator[Resource, None]:
         """Asynchronously get tenant scoped resources and folder scoped resources (accessible to the user).
 
         If no folder identifier is provided (path or key) only tenant resources will be retrieved.
@@ -428,7 +428,7 @@ async def list_by_type_async(
         folder_path: Optional[str] = None,
         folder_key: Optional[str] = None,
         page_size: int = _DEFAULT_PAGE_SIZE,
-    ) -> AsyncIterator[Resource]:
+    ) -> AsyncGenerator[Resource, None]:
         """Asynchronously get resources of a specific type (tenant scoped or folder scoped).
 
         If no folder identifier is provided (path or key) only tenant resources will be retrieved.

packages/uipath-platform/uv.lock

@@ -1,6 +1,6 @@
 [project]
 name = "uipath"
-version = "2.10.51"
+version = "2.10.52"
 description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath/pyproject.toml

@@ -0,0 +1,177 @@
+from typing import AsyncIterator
+
+from uipath.platform.connections import ConnectionsService
+from uipath.platform.errors import EnrichedException, FolderNotFoundException
+from uipath.platform.resource_catalog import (
+    Resource,
+    ResourceCatalogService,
+    ResourceType,
+)
+
+from .._utils._studio_project import (
+    ReferencedResourceFolder,
+    ReferencedResourceRequest,
+    VirtualResourceRequest,
+)
+from ..models.runtime_schema import BindingResource, Bindings
+from ._resource_actions import CreateReference, CreateVirtual, ResourceAction, Skip
+
+_NOT_FOUND_SUFFIX = "was not found and will not be added to the solution."
+
+
+async def resolve_bindings(
+    bindings: Bindings,
+    resource_catalog: ResourceCatalogService,
+    connections: ConnectionsService,
+    supported_virtual_kinds: set[str],
+) -> AsyncIterator[ResourceAction]:
+    """Yield one ResourceAction per importable binding.
+
+    Bindings that should be silently ignored (e.g. guardrail bindings without a
+    folderPath) are filtered out here.
+    """
+    for binding in bindings.resources:
+        action = await _resolve_binding(
+            binding, resource_catalog, connections, supported_virtual_kinds
+        )
+        if action is not None:
+            yield action
+
+
+async def _resolve_binding(
+    binding: BindingResource,
+    resource_catalog: ResourceCatalogService,
+    connections: ConnectionsService,
+    supported_virtual_kinds: set[str],
+) -> ResourceAction | None:
+    if binding.resource == "connection":
+        return await _resolve_connection(binding, resource_catalog, connections)
+    return await _resolve_regular(binding, resource_catalog, supported_virtual_kinds)
+
+
+async def _resolve_connection(
+    binding: BindingResource,
+    resource_catalog: ResourceCatalogService,
+    connections: ConnectionsService,
+) -> ResourceAction | None:
+    connection_id_value = binding.value.get("ConnectionId")
+    if connection_id_value is None:
+        raise ValueError(
+            f"Connection binding {binding.key!r} is missing required field 'ConnectionId'"
+        )
+    connection_key = connection_id_value.default_value
+
+    try:
+        connection = await connections.retrieve_async(connection_key)
+    except EnrichedException:
+        connector_name = (binding.metadata or {}).get("Connector")
+        return Skip(
+            message=(
+                f"Connection with key '{connection_key}' of type "
+                f"'{connector_name}' {_NOT_FOUND_SUFFIX}"
+            )
+        )
+
+    resource_name: str = connection.name
+    folder_path: str = connection.folder.get("path")
+
+    found = await _find_in_resource_catalog(
+        resource_catalog, "connection", resource_name, folder_path
+    )
+    if found is None:
+        return Skip(
+            message=(
+                f"Resource '{resource_name}' of type 'connection' at folder path "
+                f"'{folder_path}' {_NOT_FOUND_SUFFIX}"
+            )
+        )
+    return _build_create_reference(found, resource_name)
+
+
+async def _resolve_regular(
+    binding: BindingResource,
+    resource_catalog: ResourceCatalogService,
+    supported_virtual_kinds: set[str],
+) -> ResourceAction | None:
+    name_value = binding.value.get("name")
+    folder_path_value = binding.value.get("folderPath")
+    if not folder_path_value:
+        # guardrail resource, nothing to import
+        return None
+    if name_value is None:
+        raise ValueError(f"Binding {binding.key!r} is missing required field 'name'")
+    resource_name: str = name_value.default_value
+    folder_path: str = folder_path_value.default_value
+    resource_type: str = binding.resource
+
+    found = await _find_in_resource_catalog(
+        resource_catalog, resource_type, resource_name, folder_path
+    )
+    if found is not None:
+        return _build_create_reference(found, resource_name)
+
+    if resource_type not in supported_virtual_kinds:
+        return Skip(
+            message=(
+                f"Cannot create virtual resource '{resource_name}' — "
+                f"kind '{resource_type}' is not supported."
+            )
+        )
+
+    sub_type: str | None = (binding.metadata or {}).get("SubType")
+    return CreateVirtual(
+        request=VirtualResourceRequest(
+            kind=resource_type,
+            name=resource_name,
+            type=sub_type,
+        )
+    )
+
+
+async def _find_in_resource_catalog(
+    resource_catalog: ResourceCatalogService,
+    resource_type: str,
+    name: str,
+    folder_path: str,
+) -> Resource | None:
+    """Look up a single resource in the Resource Catalog.
+
+    Returns the first match or None if the catalog can't search this kind, the
+    folder is unknown, or no resource matches.
+    """
+    catalog_type = next(
+        (m for m in ResourceType if m.value == resource_type.lower()), None
+    )
+    if catalog_type is None:
+        return None
+
+    resources = resource_catalog.list_by_type_async(
+        resource_type=catalog_type, name=name, folder_path=folder_path
+    )
+    try:
+        return await anext(resources, None)
+    except FolderNotFoundException:
+        return None
+    finally:
+        await resources.aclose()
+
+
+def _build_create_reference(
+    found_resource: Resource, resource_name: str
+) -> CreateReference:
+    folder = next(iter(found_resource.folders))
+    return CreateReference(
+        request=ReferencedResourceRequest(
+            key=found_resource.resource_key,
+            kind=found_resource.resource_type,
+            type=found_resource.resource_sub_type,
+            folder=ReferencedResourceFolder(
+                folder_key=folder.key,
+                fully_qualified_name=folder.fully_qualified_name,
+                path=folder.path,
+            ),
+        ),
+        resource_name=resource_name,
+        kind=found_resource.resource_type,
+        sub_type=found_resource.resource_sub_type,
+    )

packages/uipath/src/uipath/_cli/_push/_resolvers.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+
+from .._utils._studio_project import (
+    ReferencedResourceRequest,
+    VirtualResourceRequest,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CreateReference:
+    request: ReferencedResourceRequest
+    resource_name: str
+    kind: str
+    sub_type: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class CreateVirtual:
+    request: VirtualResourceRequest
+
+
+@dataclass(frozen=True, slots=True)
+class Skip:
+    message: str
+
+
+ResourceAction = CreateReference | CreateVirtual | Skip

packages/uipath/src/uipath/_cli/_push/_resource_actions.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+
+import click
+
+
+@dataclass
+class ResourceImportSummary:
+    created: int = 0
+    updated: int = 0
+    unchanged: int = 0
+    virtual_created: int = 0
+    virtual_existing: int = 0
+    not_found: int = 0
+
+    @property
+    def total(self) -> int:
+        return (
+            self.created
+            + self.updated
+            + self.unchanged
+            + self.virtual_created
+            + self.virtual_existing
+            + self.not_found
+        )
+
+    def __str__(self) -> str:
+        return (
+            f"\n \U0001f535 Resource import summary: {self.total} total resources - "
+            f"{click.style(str(self.created), fg='green')} created, "
+            f"{click.style(str(self.updated), fg='blue')} updated, "
+            f"{click.style(str(self.unchanged), fg='yellow')} unchanged, "
+            f"{click.style(str(self.virtual_created), fg='green')} virtual-created, "
+            f"{click.style(str(self.virtual_existing), fg='yellow')} virtual-existing, "
+            f"{click.style(str(self.not_found), fg='red')} not found"
+        )

packages/uipath/src/uipath/_cli/_push/_summary.py

@@ -0,0 +1,34 @@
+import logging
+
+from .._utils._studio_project import ResourceBuilderMetadataEntry, StudioClient
+
+logger = logging.getLogger(__name__)
+
+_FALLBACK: frozenset[str] = frozenset(
+    {"app", "asset", "bucket", "process", "queue", "taskCatalog", "trigger"}
+)
+
+
+async def fetch_supported_virtual_kinds(studio_client: StudioClient) -> set[str]:
+    """Return the set of resource kinds that support inline creation.
+
+    Falls back to a static list on any failure — the caller shouldn't have to
+    care whether the metadata endpoint was reachable.
+    """
+    try:
+        metadata = await studio_client.get_resource_builder_metadata()
+    except Exception as e:
+        logger.debug("Resource Builder metadata fetch failed, using fallback: %s", e)
+        return set(_FALLBACK)
+    return _extract_supported_kinds(metadata)
+
+
+def _extract_supported_kinds(
+    metadata: list[ResourceBuilderMetadataEntry],
+) -> set[str]:
+    # metadata has one entry per (kind, type), so a kind may appear multiple times
+    return {
+        entry.kind
+        for entry in metadata
+        if any(version.supports_in_line_creation for version in entry.versions)
+    }