@uipath/skills 1.195.0

package/skills/uipath-platform/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: uipath-platform
+description: "UiPath platform ops via the uip CLI — use this skill for ANY task hitting UiPath Cloud / Orchestrator / Studio Web / Integration Service / LLM Gateway. Load BEFORE writing any code that calls a UiPath API. Covers auth, folders, assets, queues, storage buckets, bucket files, libraries, webhooks, triggers, processes, jobs, machines, users, roles, sessions, calendars, IS connectors/connections/activities, BYO LLM product configurations (`uip llm-configuration byo-connections` — register / audit / re-probe / troubleshoot tenant-owned OpenAI / Azure OpenAI / Bedrock / Vertex / Anthropic keys against UiPath products), traces, licensing. For `uip solution` lifecycle and PDD/SDD authoring→uipath-solution. For workflow code (.xaml/.cs)→uipath-rpa, .flow→uipath-maestro-flow, .bpmn→uipath-maestro-bpmn, agents (.py/agent.json)→uipath-agents, Test Manager→uipath-test."
+when_to_use: "User mentions UiPath / Orchestrator / Studio Web / Integration Service / LLM Gateway / 'uip' CLI / asset / queue / bucket / library / webhook / trigger / connector / connection / tenant / folder / robot / package / BYO LLM. Also 'upload to UiPath', 'create asset', 'start job', 'list queues', 'deploy a single package to Orchestrator', 'OAuth2 token', 'register my own LLM key', 'configure a model substitution', 'my BYO LLM key stopped working / returns errors', 're-probe / audit a BYO configuration', 'uipath.com REST'. Load BEFORE composing any HTTP request — most UiPath tasks have a `uip` command. For `uip solution` ops or `.uipx` deploys→uipath-solution."
+allowed-tools: Bash, Read, Write, Glob, Grep
+---
+
+# UiPath Platform — uip CLI Assistant
+
+Comprehensive guide for UiPath Cloud / Orchestrator / Studio Web / Integration Service, end-to-end via the `uip` CLI. For `uip solution` lifecycle and PDD/SDD authoring, load [`uipath-solution`](/uipath:uipath-solution).
+
+## Use the CLI. Don't roll your own REST.
+
+**Always reach for `uip` CLI commands first.** The CLI covers auth, Orchestrator (folders, processes, jobs, machines, users, roles, sessions, calendars, settings, audit logs, credential stores, feeds, attachments), resources (assets, queues, queue items, storage buckets, bucket files, libraries, webhooks, triggers), Integration Service (connectors, connections, activities, IS triggers), traces, and licensing end-to-end.
+
+Hand-rolling HTTP calls — reading `~/.uipath/.auth` and POSTing to `/odata/...` or `/orchestrator_/...` — almost always misses something the CLI gets right: the `X-UIPATH-OrganizationUnitId` folder header, OData filter shape (`Key eq '...'` with escaped single quotes), pagination envelope, retry semantics, validation error shape, or `Result/Code/Data` output contract. **Reach for raw REST only after you've searched [`references/uip-commands.md`](references/uip-commands.md) for your task and confirmed no `uip` command covers it.** The CLI is the source of truth.
+
+If you find yourself about to `curl` `https://cloud.uipath.com/...` — stop. Search the command index first. Examples of what people often miss:
+
+- "upload a file to a storage bucket" → `uip resource bucket-files upload` (NOT a `PUT /buckets/.../signedUrl` dance)
+- "create an asset" → `uip resource assets create` (NOT a `POST /odata/Assets`)
+- "start a job for a process" → `uip or jobs start <process-key>` (NOT `POST /odata/Jobs/UiPath.Server.Configuration.OData.StartJobs`)
+- "configure an Integration Service connection" → `uip is connections create <connector-key>` (NOT a hand-rolled OAuth flow)
+
+## When to Use This Skill
+
+Load this skill BEFORE writing any code that talks to UiPath. Specific triggers:
+
+- **Auth & tenant**: login, logout, switch tenant, `~/.uipath/.auth`, OAuth token, organization
+- **Orchestrator core**: folders (`list/get/create/edit/move/delete/runtimes`), processes/releases, jobs (`start/stop/logs/traces/healing-data`), packages (`upload/download/versions`), machines, users / roles / sessions (incl. DirectoryUser/DirectoryGroup/DirectoryRobot/DirectoryExternalApplication), licenses, calendars, settings, audit logs, credential stores, feeds, attachments
+- **Resources (Orchestrator-scoped)**: assets (text/integer/bool/credential), queues + queue items, storage buckets + bucket files (`upload/download/get-download-url/get-upload-url`), libraries (`.nupkg`), webhooks (HMAC signing), triggers (time/queue/api)
+- **Integration Service**: connectors, connections (OAuth flow), activities, IS triggers, agent-workflow reference resolution
+- **LLM Gateway — BYO product configurations**: `uip llm-configuration byo-connections` (`list / get / create / update / delete / list-product-configs`). Register tenant-owned OpenAI / Azure OpenAI / AWS Bedrock / Google Vertex / Anthropic / OpenAI-compatible keys against UiPath product features (agents, agenthub, jarvis, IXP, agent builder, ECS). Two input shapes: single-mapping (for `AnyModelWithOwnAdditions` features) and repeated `--mapping` (required for `AllModels` / `AnyModel`). Server-side validation is mandatory.
+- **LLM Gateway — diagnose a failing BYO config**: re-probe the underlying IS connection with `byo-connections get <id> --force-refresh`, force a fresh server-side probe with an idempotent `update`, audit the tenant with `list --include-connection-details` filtered on `connectionState != Enabled`, check catalog drift with `list-product-configs`, and cross-reference trace evidence with `uip traces spans get <trace-id>`. The gateway does **not** expose per-request invocation logs via CLI — diagnosis is current-state + trace evidence only. See [`references/llmgateway/byo-connections.md` § Diagnostics](references/llmgateway/byo-connections.md#diagnostics). For tenant-wide AI Trust Layer policy that may be overriding routing, see [uipath-governance](/uipath:uipath-governance).
+- **Traces**: `uip traces spans get [trace-id]` (LLM/agentic execution observability)
+- **Platform licensing**: tenant license allocations, user/group bundle assignments, consumables reporting (`uip platform tenants licenses`, `users licenses`, `groups rules`, `licenses consumables`)
+- **CLI tooling itself**: `uip tools list/search/install`, `uip mcp serve`
+
+For `uip solution` lifecycle (init / pack / publish / deploy / activate / upload) and CI/CD pipelines that build and deploy UiPath solutions, load [`uipath-solution`](/uipath:uipath-solution).
+
+## Auth token location
+
+The CLI stores credentials at **`~/.uipath/.auth`** after login:
+```
+UIPATH_URL=https://alpha.uipath.com
+UIPATH_ORG_NAME=my_org
+UIPATH_TENANT_NAME=my_tenant
+UIPATH_ACCESS_TOKEN=eyJ...
+UIPATH_ORGANIZATION_ID=...
+UIPATH_TENANT_ID=...
+```
+
+This token can be reused for direct Orchestrator REST API calls when CLI commands don't cover a use case.
+
+## Quick Start
+
+### Step 1 — Authenticate
+
+Before interacting with Orchestrator, solutions, or Integration Service, the user must be logged in.
+
+**Interactive login (browser OAuth2):**
+```bash
+uip login --output json
+```
+
+For a custom authority (e.g., alpha.uipath.com):
+```bash
+uip login --authority "https://alpha.uipath.com/identity_" --it --output json
+```
+
+For non-interactive (CI/CD) scenarios, use client credentials:
+```bash
+uip login --client-id "<ID>" --client-secret "<SECRET>" --tenant "<TENANT>" --output json
+```
+
+Check login status:
+```bash
+uip login status --output json
+```
+
+### Step 2 — Select a Tenant
+
+List available tenants and set the active one:
+
+```bash
+uip login tenant list --output json
+uip login tenant set "<TENANT_NAME>" --output json
+```
+
+### Step 3 — Explore Orchestrator
+
+List folders to orient yourself:
+```bash
+uip or folders list --output json
+```
+
+### Step 4 — Work with Orchestrator Resources
+
+Choose the appropriate operation from the Task Navigation table below. For `uip solution` ops, load [`uipath-solution`](/uipath:uipath-solution).
+
+## Task Navigation
+
+| I need to... | Read these |
+|---|---|
+| **Authenticate / manage tenants** | [references/uip-commands.md](references/uip-commands.md) |
+| **Set up folders, users, machines** | [references/orchestrator/setup-environment.md](references/orchestrator/setup-environment.md) |
+| **Run and monitor jobs** | [references/orchestrator/run-jobs.md](references/orchestrator/run-jobs.md) |
+| **Manage sessions and runtimes** | [references/orchestrator/manage-sessions.md](references/orchestrator/manage-sessions.md) |
+| **Tenant settings, calendars, audit logs** | [references/orchestrator/tenant-admin.md](references/orchestrator/tenant-admin.md) |
+| **Understand Orchestrator concepts** | [references/orchestrator/orchestrator.md](references/orchestrator/orchestrator.md) |
+| **Manage assets** | [references/resources/manage-assets.md](references/resources/manage-assets.md) |
+| **Work with queues and queue items** | [references/resources/process-queues.md](references/resources/process-queues.md) |
+| **Work with storage buckets and files** | [references/resources/work-with-storage.md](references/resources/work-with-storage.md) |
+| **Set up triggers and webhooks** | [references/resources/triggers-and-webhooks.md](references/resources/triggers-and-webhooks.md) |
+| **Develop / pack / publish / deploy / activate solutions; set up CI/CD** | [/uipath:uipath-solution](/uipath:uipath-solution) |
+| **Debug LLM/agent traces (spans)** | [references/traces/traces.md](references/traces/traces.md) |
+| **Annotate traces with feedback** | [references/traces/feedback.md](references/traces/feedback.md) |
+| **Use Integration Service** | [references/integration-service/integration-service.md](references/integration-service/integration-service.md) |
+| **Configure BYO LLM keys (OpenAI / Azure OpenAI / Bedrock / Vertex / Anthropic)** | [references/llmgateway/byo-connections.md](references/llmgateway/byo-connections.md) |
+| **Diagnose / audit / re-probe a BYO LLM configuration** | [references/llmgateway/byo-connections.md#diagnostics](references/llmgateway/byo-connections.md#diagnostics) |
+| **Allocate licenses to tenants** | [references/licensing/tenant-allocations.md](references/licensing/tenant-allocations.md) |
+| **Assign user/group license bundles** | [references/licensing/user-licenses-allocations.md](references/licensing/user-licenses-allocations.md) |
+| **Report on license consumption** | [references/licensing/consumables-report.md](references/licensing/consumables-report.md) |
+| **Understand licensing concepts** | [references/licensing/licensing.md](references/licensing/licensing.md) |
+| **Full CLI command reference** | [references/uip-commands.md](references/uip-commands.md) |
+| **Build/run/validate coded workflows** | [/uipath:uipath-rpa](/uipath:uipath-rpa) |
+
+## Resolving UiPath Studio
+
+Some operations (creating projects, validating, running workflows, packing) require UiPath Studio. When Studio is needed:
+
+1. **Check for a running instance first:**
+   ```bash
+   rpa-tool list-instances --output json
+   ```
+
+2. **If no instance is running, try the standard install location:**
+   ```bash
+   rpa-tool start-studio --output json
+   ```
+
+3. **If that fails (version too old, not found, etc.) — ASK THE USER where their Studio build is located.** Do NOT search the entire filesystem. Common locations include:
+   - `C:\Program Files\UiPath\Studio`
+   - A dev build directory (e.g., `dev4/Studio/Output/bin/Debug`)
+   - A custom install path
+
+4. **Once you have the path, pass it explicitly:**
+   ```bash
+   rpa-tool start-studio --studio-dir "<STUDIO_DIR>" --output json
+   ```
+
+> **Never spend time searching for Studio automatically.** If the default doesn't work, ask immediately — the user knows where their build is.
+
+## Key Concepts
+
+### UiPath Platform Hierarchy
+
+```
+Organization
+  └── Tenant(s)
+        └── Folder(s)              ← Orchestrator folders (logical containers)
+              ├── Processes         ← Published automation packages
+              ├── Assets            ← Key-value configuration (Text, Bool, Integer, Credential, Secret)
+              ├── Queues            ← Work item queues for distributed processing
+              ├── Jobs              ← Running/completed process executions
+              ├── Triggers          ← Event-based or queue-based job triggers
+              ├── Schedules         ← Time-based job scheduling (cron)
+              ├── Storage Buckets   ← File storage for automation data
+              ├── Machines          ← Robot execution environments
+              └── Robots            ← Attended/Unattended execution agents
+```
+
+### Robot Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| **Attended** | Runs alongside a human user, triggered via UiPath Assistant | Front-office tasks, user-assisted automation |
+| **Unattended** | Runs autonomously in virtual environments, managed by Orchestrator | Back-office tasks, scheduled processing, 24/7 operations |
+
+### Folder Types
+
+| Type | Description |
+|------|-------------|
+| **Standard** | Default folder for organizing automations |
+| **Personal** | User-specific workspace |
+| **Virtual** | Logical grouping without physical separation |
+| **Solution** | Folder created by solution deployment |
+| **DebugSolution** | Debug variant of a solution folder |
+
+### Asset Types
+
+| Type | Description |
+|------|-------------|
+| **Text** | Plain text value |
+| **Bool** | Boolean (true/false) |
+| **Integer** | Numeric integer value |
+| **Credential** | Username + password pair |
+| **Secret** | Encrypted secret value |
+| **DBConnectionString** | Database connection string |
+| **HttpConnectionString** | HTTP connection string |
+| **WindowsCredential** | Windows credential pair |
+
+## CLI Overview
+
+The UiPath CLI (`uip`) is a unified command-line tool for interacting with the UiPath platform:
+
+| Command Group | Prefix | Description | Status |
+|---|---|---|---|
+| **Authentication** | `login`, `logout` | OAuth2, client credentials, PAT, tenant management | Available |
+| **Orchestrator** | `or` | Folders, jobs, processes, releases | Available |
+| **Resource** | `resource` | Assets, queues, queue items, storage buckets, bucket files | Available |
+| **Integration Service** | `is` | Connectors, connections, activities, resources | Available |
+| **Test Manager** | `tm` | Test projects, test sets, test cases, executions, reports | Available |
+| **Tools** | `tools` | CLI tool extension management | Available |
+| **MCP** | `mcp` | Model Context Protocol server | Available |
+| **Coded Agents** | `codedagent` | Python agent lifecycle (setup, exec) | Available |
+| **RPA** | `rpa` | RPA workflow management (create, compile, validate, execute) | Available |
+
+### Global Options
+
+Every `uip` command accepts:
+
+| Option | Description | Default |
+|---|---|---|
+| `--output <format>` | Output format: `table`, `json`, `yaml`, `plain` | `table` (interactive), `json` (non-interactive) |
+| `--output-filter <expression>` | JMESPath expression to filter JSON output | -- |
+| `--verbose` | Enable verbose/debug logging | Off |
+| `--help` / `-h` | Display help for the command | -- |
+| `--version` / `-v` | Display CLI version | -- |
+
+> **Always use `--output json`** when calling `uip` commands programmatically. JSON is compact and machine-readable.
+>
+> **To narrow `list` results, use the noun's own filter flag** (`--state Faulted`, `--type Text`, `--status New`, `--name`, `--process-name`, `--search`). The backend filters before sending; pagination stays correct. Per-noun flags: [references/uip-commands.md](references/uip-commands.md). Never list-everything-then-filter-mentally.
+>
+> **Use `--output-filter` (JMESPath) for output reshaping** or for fields with no server-side flag — e.g., `--output-filter "Data[].{id: id, name: name}"`, or filtering by a derived/computed value. Don't reach for it when the server already has a filter for that attribute.
+
+## Deployment Notes
+
+- **Starting jobs requires runtimes.** If you get error 2818 "no runtimes configured", the target folder needs machine templates with Unattended/Development runtimes assigned.
+- **For `uip solution` pack / publish / deploy / activate flows, load [`uipath-solution`](/uipath:uipath-solution).** This skill owns the auth and Orchestrator surface those flows depend on; the solution skill owns the lifecycle commands.
+- **Fallback: direct REST API.** When CLI tools don't support an operation, use the Orchestrator REST API with the access token from `~/.uipath/.auth`. See [references/orchestrator/orchestrator.md - REST API](references/orchestrator/orchestrator.md).
+
+## Orchestrator REST API (Fallback)
+
+When CLI commands are insufficient, use the Orchestrator REST API directly with the stored access token:
+
+```bash
+source ~/.uipath/.auth
+
+# Upload a .nupkg package
+curl -X POST "${UIPATH_URL}/${UIPATH_ORG_NAME}/${UIPATH_TENANT_NAME}/orchestrator_/odata/Processes/UiPath.Server.Configuration.OData.UploadPackage" \
+  -H "Authorization: Bearer ${UIPATH_ACCESS_TOKEN}" \
+  -H "X-UIPATH-OrganizationUnitId: <FOLDER_ID>" \
+  -F "file=@./MyProject.1.0.0.nupkg"
+
+# Create a process (release) from an uploaded package
+curl -X POST "${UIPATH_URL}/${UIPATH_ORG_NAME}/${UIPATH_TENANT_NAME}/orchestrator_/odata/Releases" \
+  -H "Authorization: Bearer ${UIPATH_ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "X-UIPATH-OrganizationUnitId: <FOLDER_ID>" \
+  -d '{"Name":"MyProcess","ProcessKey":"MyProject","ProcessVersion":"1.0.0"}'
+
+# Start a job
+curl -X POST "${UIPATH_URL}/${UIPATH_ORG_NAME}/${UIPATH_TENANT_NAME}/orchestrator_/odata/Jobs/UiPath.Server.Configuration.OData.StartJobs" \
+  -H "Authorization: Bearer ${UIPATH_ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "X-UIPATH-OrganizationUnitId: <FOLDER_ID>" \
+  -d '{"startInfo":{"ReleaseKey":"<RELEASE_KEY>","Strategy":"ModernJobsCount","JobsCount":1,"RuntimeType":"Unattended","InputArguments":"{}"}}'
+```
+
+The `X-UIPATH-OrganizationUnitId` header is the **folder ID** (get it from `uip or folders list`).
+
+## References
+
+- **[CLI Command Reference](references/uip-commands.md)** — Every `uip` command with workflow links
+- **[Orchestrator](references/orchestrator/orchestrator.md)** — Concepts, folders, jobs, processes, machines, users
+- **[Resources](references/resources/resources.md)** — Assets, queues, buckets, triggers, libraries, webhooks
+- **[Solutions](/uipath:uipath-solution)** — Solution lifecycle (`uip solution init/pack/publish/deploy/activate`) and PDD/SDD authoring
+- **[Traces — Spans](references/traces/traces.md)** — LLM execution trace observability
+- **[Traces — Feedback](references/traces/feedback.md)** — Annotate traces with sentiment and comments
+- **[Integration Service](references/integration-service/integration-service.md)** — Connectors, connections, activities, resources
+- **[LLM Gateway — BYO Connections](references/llmgateway/byo-connections.md)** — Register tenant-owned LLM keys against UiPath products
+- **[Licensing](references/licensing/licensing.md)** — Tenant allocations, user/group bundles, consumables reporting
+- **[Coded Workflows](/uipath:uipath-rpa)** — Building coded automation projects
+
+> **Trouble?** If something didn't work as expected, use `/uipath-feedback` to send a report.

package/skills/uipath-platform/references/integration-service/activities.md

@@ -0,0 +1,223 @@
+# Activities
+
+Activities are pre-built actions available for each connector (e.g., "Send Message", "Create Issue"). They represent specific operations the connector supports. Activities include both **actions** (non-trigger) and **triggers** (event listeners).
+
+> Full command syntax and options: [uip-commands.md — Integration Service](../uip-commands.md#integration-service-is). Domain-specific usage patterns are shown inline below.
+
+---
+
+## List Activities (Non-Trigger)
+
+Use the connector **Key**, not the display name. For Salesforce, the canonical key is `uipath-salesforce-sfdc`; do not pass `salesforce` or `uipath-salesforce` to activity commands.
+
+```bash
+uip is activities list "<connector-key>" --output json
+```
+
+```bash
+uip is activities list "uipath-salesforce-sfdc" --output json
+```
+
+This lists **non-trigger activities only** (actions, not event listeners).
+
+## List Trigger Activities
+
+```bash
+uip is activities list "<connector-key>" --triggers --output json
+```
+
+```bash
+uip is activities list "uipath-salesforce-sfdc" --triggers --output json
+```
+
+The `--triggers` flag filters to **trigger activities only** (`isTrigger=true`). These represent events the connector can fire (e.g., "Record Created", "Record Updated").
+
+The **Operation** field on trigger activities indicates the trigger type:
+- **CREATED** / **UPDATED** / **DELETED** — CRUD event triggers (require an intermediate "objects" step to discover which objects support the operation)
+- Other values — custom event triggers (skip directly to metadata)
+
+> When a trigger activity is selected, proceed to [triggers.md](triggers.md) for the trigger metadata workflow.
+
+## Response Fields
+
+| Field | Description |
+|---|---|
+| **`Name`** | Activity identifier |
+| `DisplayName` | Human-readable name (e.g., "HTTP Request", "Send Message") |
+| `Description` | What the activity does |
+| **`ObjectName`** | The resource object this activity operates on (use as `<object-name>` in trigger describe for non-CRUD triggers) |
+| `MethodName` | HTTP method used (GET, POST, etc.) |
+| **`Operation`** | Operation type — for triggers, this is the event type (CREATED, UPDATED, DELETED, or custom) |
+| `IsCurated` | Whether this is a curated/recommended activity |
+
+---
+
+## When to Use Activities vs Resources vs Triggers
+
+- **Activities** = named actions (e.g., "Send Email"). Discovered via `is activities list`.
+- **Triggers** = event listeners (e.g., "Record Created"). Discovered via `is activities list --triggers`. Metadata via `is triggers objects` / `is triggers describe`. See [triggers.md](triggers.md).
+- **Resources** = data objects with CRUD (e.g., "Account"). Discovered via `is resources list`. Executed via `is resources run <verb>`.
+
+> After listing activities, present the available actions to the user. Activities provide context for what a connector can do — use this to guide which resource operations, triggers, or workflow actions to pursue.
+
+---
+
+## Filter Trees (CEQL)
+
+Some IS activities — most notably **List All Records** and other list/query operations — accept a server-side filter expressed in **CEQL** (Connector Expression Query Language). As with trigger filters (which compile to JMESPath), CEQL filters are authored as a **structured filter tree** and the CLI compiles them to a CEQL string. Authoring as a tree keeps the CLI and Studio Web in lockstep so the activity round-trips cleanly when re-opened in SW.
+
+### Contract — three signals from IS metadata
+
+The CLI reads the live IS metadata response and uses three signals to wire the filter:
+
+1. **The activity supports CEQL** when one of its `parameters` declares `design.component === "FilterBuilder"`. That parameter's `name` is the connector-specific key the compiled CEQL string is sent under — most commonly `where`, but **not always** (e.g. Salesforce uses `q`). Activities with no such parameter do not support server-side filtering — pass no `filter` and filter downstream.
+2. **A field is filterable** when its IS metadata entry has `searchable: true`. Type alone does not gate it — the connector flags fields explicitly. Fields without `searchable: true` are rejected by the CLI even if they look like primitives.
+3. **Permitted operators** for the field are listed under `searchableOperators`. **Connector-side identifier** for the field in CEQL is `searchableNames[0]` when present (some connectors expose a friendly `name` but require a different identifier in the query string).
+
+### What the CLI persists from a single `filter` input
+
+- **Runtime side** — the compiled CEQL string lands at `inputs.detail.queryParameters.<filterParamName>` where `<filterParamName>` is the FilterBuilder parameter's name from the IS metadata (often `where`).
+- **Design-time side** — the structured tree is embedded under `inputs.detail.configuration`'s `essentialConfiguration.savedFilterTrees.<filterParamName>`. Studio Web reads this on open to re-render the filter widget; without it the filter UI shows up empty even though the runtime call still works.
+
+Pass `filter` (the structured tree) and the CLI emits both halves in lockstep. Passing both `filter` and `queryParameters.<filterParamName>` is rejected at validation time — single source of truth.
+
+### Tree shape
+
+Identical to the trigger filter tree — the same `FilterTree` / `Filter` / `WorkflowValue` types are used; only the compiler output (CEQL vs JMESPath) differs.
+
+```jsonc
+{
+  "groupOperator": 0,             // 0 = And, 1 = Or — combines sibling filters/groups
+  "index": 0,                     // ordering index within parent (root is 0)
+  "filters": [                    // leaf conditions at this level
+    {
+      "id": "<fieldName>",        // resource field name from `is resources describe`
+      "operator": "<Operator>",   // PascalCase, see operator table below
+      "value": {
+        "value": <typed value>,   // string / number / boolean / ISO-8601 date-time / array
+        "rawString": "\"...\"",   // verbatim user-entered text (with quotes for strings)
+        "isLiteral": true         // literals only — expression values are not yet supported
+      }
+    }
+  ],
+  "groups": []                    // optional: nested subgroups (same shape as root)
+}
+```
+
+A no-op filter — used when the user wants to list all records without restriction — is `null` or `{"groupOperator": null, "index": 0, "filters": []}`. Prefer **omitting** the `filter` field entirely.
+
+### Compiled CEQL output
+
+The CLI compiles each leaf to `<field> <op> <value>` (or `<field> <function>` for null checks) and joins siblings with the group operator. String values are wrapped in single quotes; booleans, numerics, and enums are passed bare.
+
+| Operator | CEQL token | Notes |
+|---|---|---|
+| `Equals` | `=` | |
+| `NotEquals` | `!=` | |
+| `LessThan` / `LessThanOrEqual` / `GreaterThan` / `GreaterThanOrEqual` | `<` / `<=` / `>` / `>=` | Numeric / date-time |
+| `Contains` / `NotContains` | `Contains` / `Not Contains` | Substring (string) |
+| `StartsWith` / `NotStartsWith` / `EndsWith` / `NotEndsWith` | `Starts With` / `Not Starts With` / `Ends With` / `Not Ends With` | String |
+| `Like` / `NotLike` | `Like` / `Not Like` | Pattern match (connector-specific) |
+| `In` / `NotIn` | `In` / `Not In` | Membership — `value.value` is a list; rendered as `(v1, v2, …)` |
+| `IsNull` / `IsNotNull` | `Is Null` / `Is Not Null` | No `value` needed |
+| `Is` / `IsNot` | `=` against literal `true` / `false` | Boolean shortcut |
+
+Logical operators between siblings:
+
+| `groupOperator` | CEQL token |
+|---|---|
+| `0` (And) | ` AND ` |
+| `1` (Or) | ` OR ` |
+
+### Examples
+
+**Active accounts only:**
+
+```json
+{
+  "groupOperator": 0, "index": 0,
+  "filters": [
+    { "id": "Status", "operator": "Equals",
+      "value": { "value": "Active", "rawString": "\"Active\"", "isLiteral": true } }
+  ]
+}
+```
+→ CEQL: `Status = 'Active'`
+
+**Score ≥ 80 AND Region in (EMEA, APAC):**
+
+```json
+{
+  "groupOperator": 0, "index": 0,
+  "filters": [
+    { "id": "Score", "operator": "GreaterThanOrEqual",
+      "value": { "value": 80, "rawString": "80", "isLiteral": true } },
+    { "id": "Region", "operator": "In",
+      "value": { "value": ["EMEA", "APAC"], "rawString": "[\"EMEA\",\"APAC\"]", "isLiteral": true } }
+  ]
+}
+```
+→ CEQL: `Score >= 80 AND Region In ('EMEA', 'APAC')`
+
+**Subject contains "urgent" AND (owner = me OR owner is null):**
+
+```json
+{
+  "groupOperator": 0, "index": 0,
+  "filters": [
+    { "id": "Subject", "operator": "Contains",
+      "value": { "value": "urgent", "rawString": "\"urgent\"", "isLiteral": true } }
+  ],
+  "groups": [
+    {
+      "groupOperator": 1, "index": 1,
+      "filters": [
+        { "id": "OwnerId", "operator": "Equals",
+          "value": { "value": "${me.id}", "rawString": "\"${me.id}\"", "isLiteral": false } },
+        { "id": "OwnerId", "operator": "IsNull" }
+      ]
+    }
+  ]
+}
+```
+→ CEQL: `Subject Contains 'urgent' AND (OwnerId = ${me.id} OR OwnerId Is Null)`. Non-literal values (`isLiteral: false`) are emitted as `${expression}` placeholders for runtime resolution.
+
+### How to build a CEQL filter tree
+
+1. Run `uip is resources describe "<connector-key>" "<objectName>" --connection-id "<id>" --operation List` to read the resource's metadata.
+2. **Confirm CEQL is supported** for this operation: at least one entry under `parameters` must carry `design.component === "FilterBuilder"`. If none does, the activity does not support server-side filtering — omit `filter` and filter downstream (e.g. with a Script node).
+3. **Pick filterable fields** from `fields[]` where `searchable: true`. Other fields will be rejected by the CLI at configure time even if they look like primitives.
+4. For each leaf, pick an operator from the field's `searchableOperators` list (when present). Date-time fields take ISO-8601 strings; enums take the literal enum value.
+5. Use the field's `name` as the leaf `id`. The CLI rewrites it to `searchableNames[0]` when emitting CEQL if the connector declares one — you don't need to use the alias yourself.
+6. Build one leaf per condition; place multiple conditions under the same `groupOperator` (0 for AND, 1 for OR). Use nested `groups` for mixed AND/OR.
+7. Wrap values in a `WorkflowValue` object with `value`, `rawString`, `isLiteral`. Strings, numbers, booleans, dates, and arrays are all valid `value` types; only `isLiteral: true` is currently supported by activity-side compilation.
+
+### What NOT to generate
+
+| Invalid input | Why it fails | Valid replacement |
+|---|---|---|
+| `"filter": "Status = 'Active'"` | Bare CEQL string — `filter` must be an object. | Structured tree with `filters: [...]`. |
+| `"filterExpression": "..."` | That field is reserved for the trigger (JMESPath) path. | Use `filter` (CEQL tree) for activities. |
+| `{ "operator": "equals", ... }` | Operator is case-sensitive. | `"operator": "Equals"` |
+| `{ "value": "Active" }` on a leaf | Bare string — must be wrapped in the `WorkflowValue` object. | `{ "value": { "value": "Active", "rawString": "\"Active\"", "isLiteral": true } }` |
+| `{ "id": "fields.Status", ... }` | `fields.` prefix — use the bare field name from `is resources describe`. | `{ "id": "Status", ... }` |
+| `{ "id": "<field without searchable: true>", ... }` | The CLI checks `searchable` on the IS metadata entry; non-searchable fields are rejected even if their type looks filterable. | Pick a field where `searchable: true`. |
+| `"queryParameters": { "where": "..." }` alongside `filter` | Hardcoding `where` assumes that's the FilterBuilder param name — it isn't always (Salesforce uses `q`, etc.). | Pass `filter` only; the CLI discovers the right param name from `design.component === "FilterBuilder"`. |
+| `In` operator with a single value not in a list | `In` expects an array `value`. | Use `Equals`, or pass `value: ["one"]`. |
+
+## Custom Fields (`objectActions[ActionType=Api]`)
+
+Connectors with extensible/custom fields (Jira project+issuetype → custom Jira fields, Mailchimp list_id → audience merge fields, Salesforce custom objects) expose `Api`-type entries under `objectActions[]`. Each entry's `apiConfiguration.url`/`body` carries `{token}` placeholders naming the parent fields. The runtime replays the ObjectAction with cached parent values to fetch the connector-specific custom-field schema.
+
+**For Maestro flows**, this lives on the activity node as `essentialConfiguration.customFieldsRequestDetails`. Authoring contract → [uipath-maestro-flow connector/impl.md Step 6c](../../../uipath-maestro-flow/references/author/references/plugins/connector/impl.md).
+
+Shape:
+
+```json
+"customFieldsRequestDetails": {
+  "objectActionName": "GenerateSchema",
+  "parameterValues": [["fields_sub_project_sub_key", "ENGCE"], ...]
+}
+```
+
+camelCase inner keys, `parameterValues` as `[key, value]` tuples (Studio Web emits `Map<string,string|null>` via `Array.from(entries())`). Object-map form rejected by the CLI.