@uipath/skills 1.195.0

package/skills/uipath-maestro-flow/references/author/references/plugins/connector/planning.md

@@ -0,0 +1,135 @@
+# Connector Activity Nodes — Planning
+
+Connector activity nodes call external services (Jira, Slack, Salesforce, Outlook, etc.) via UiPath Integration Service. They are dynamically loaded — not built-in — and appear in the registry after `uip login` + `uip maestro flow registry pull`.
+
+## When to Use
+
+Use a connector activity node when the flow needs to **call an external service that has a pre-built UiPath connector**. Connectors handle auth (OAuth, API keys), token refresh, and error formatting automatically at runtime. Note: design-time reference resolution (looking up records by name during authoring) still requires the agent to paginate — see [impl.md](impl.md).
+
+### Decision Order
+
+Prefer higher tiers when connecting to external services:
+
+| Tier | Approach | When to Use |
+| --- | --- | --- |
+| 1 | **IS connector activity** (this node type) | A connector exists and its activities cover the use case |
+| 2 | **Managed HTTP Request** (`core.action.http.v2`) | A connector exists but lacks the specific curated activity — uses the connector's IS connection for auth |
+| 3 | **Managed HTTP Request — manual mode** (`core.action.http.v2`) | No connector exists — you provide the full URL manually |
+| 4 | **RPA workflow** | Target system has no API at all (legacy desktop apps, terminals) |
+
+### Prerequisites
+
+- `uip login` required — connector nodes only appear in the registry after authentication
+- A healthy IS connection must exist for the connector — if none exists, the user must create one before proceeding
+- `uip maestro flow registry pull` must be run to cache connector node types locally
+
+### When NOT to Use
+
+- **No connector exists for the service** — use `core.action.http.v2` manual mode instead
+- **Simple GET request with no auth** — `core.action.http.v2` (manual mode) is simpler and faster to configure
+- **The operation needs desktop/browser interaction** — use an RPA resource node
+- **The task requires reasoning or judgment** — use an agent node
+
+## Node Type Pattern
+
+`uipath.connector.<connector-key>.<activity>`
+
+Examples:
+- `uipath.connector.uipath-salesforce-slack.send-message`
+- `uipath.connector.uipath-atlassian-jira.create-issue`
+
+## Discovery
+
+```bash
+uip maestro flow registry search <service> --output json \
+  --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}"
+```
+
+`registry search` returns `Data` as a flat array, and each row uses PascalCase fields (`NodeType`, `DisplayName`, `Description`, `AvailableOnTenant`). Do **not** parse `Data.Nodes`, lowercase `type`, or lowercase `category`; those shapes do not exist in the CLI JSON output.
+
+For connector activities, use `NodeType` as the source of truth:
+
+- Activity rows start with `uipath.connector.<connector-key>.`
+- Trigger rows start with `uipath.connector.trigger.` and belong to the connector-trigger guide
+- `NodeType` is the exact value to pass to `registry get` and `node add`
+- `Category` can be tenant/internal metadata such as `connector.<id>` and is not a reliable connector-key source
+
+If the connector key fails, list all connectors:
+
+```bash
+uip is connectors list --output json
+```
+
+Keys are often prefixed — e.g., `uipath-salesforce-slack` not `slack`.
+
+### Sanity-check before deciding "no connector activity exists"
+
+A `registry search <service>` that returns **only `uipath.connector.trigger.*`** entries — zero activity entries — is **suspicious, not authoritative**. Connector activities and triggers are independent fetches against different typecache endpoints; the registry cache can transiently miss the activity branch when one of those endpoints flakes (TTL: 30 min). Falling through to managed HTTP at this point produces a flow that *validates* but skips the real connector node — a silent topology mistake.
+
+When `registry search` returns triggers but **no activities** for a service whose connector you've already confirmed exists (`uip is connectors list`), or returns nothing at all for a well-known connector, **force a fresh pull before falling back**:
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search <service> --output json
+```
+
+If the second search still returns no activities for that connector, the fallback to managed HTTP (Tier 2 below) is legitimate. If the second search now lists activities, the cache was stale — proceed with the connector activity node as Tier 1.
+
+> **Why this matters**: a partial registry pull is an indirect failure — `registry pull` reports `Success` even when one node-source branch silently dropped its contribution. The shape (`triggers > 0 && activities == 0`) is the only local signal you have. Treat it like a stale-cache symptom, not a topology fact.
+
+### Disambiguation — when search returns multiple connectors for the same intent
+
+`uip maestro flow registry search <keyword>` routinely returns multiple connectors for the same user intent (e.g. searching `databricks` returns both the native AI-serving connector and the JDBC gateway). **Never silently pick the first match.**
+
+Apply the canonical disambiguation ladder owned by Integration Service:
+
+- [/uipath:uipath-platform — Integration Service — connectors.md — Connector Disambiguation](../../../../../../uipath-platform/references/integration-service/connectors.md#connector-disambiguation) — classify catalog/custom/mock, intent-match by `Description`, count remaining candidates (1 → silent, >1 → AskUser, 0 catalog → STOP).
+- [/uipath:uipath-platform — Integration Service — connectors.md — JDBC Gateway — Database SQL Intent](../../../../../../uipath-platform/references/integration-service/connectors.md#jdbc-gateway--database-sql-intent) — special handling when the user's intent is a database SQL operation (native connector vs JDBC gateway, connection-name keyword matching, decision matrix, lifecycle disclosure).
+
+Lock the chosen connector key in the planning notes — never re-derive per node within the same flow.
+
+### Check Connector Connections
+
+For each connector found in registry search, verify a healthy connection exists. Extract the connector key from the node type name (e.g., `uipath.connector.uipath-microsoft-outlook365.get-newest-email` -> key is `uipath-microsoft-outlook365`).
+
+**Never type a connector key from memory.** Use the key from the `registry search` node type only. The registry key is frequently prefixed or qualified differently than the service's brand name (e.g. an Outlook connector keys as `uipath-microsoft-outlook365`, not `outlook`), so a guessed key silently misses the real connector and makes `connections list` return a false "No connections found."
+
+```bash
+uip is connections list "<connector-key>" --all-folders --output json
+```
+
+> `--all-folders` is mandatory. Without it the CLI returns the active folder only and hides connections in other folders the user can see. Plain `uip is connections list "<connector-key>"` is forbidden for discovery.
+
+- If a default enabled connection exists (`IsDefault: Yes`, `State: Enabled`), record the connection ID for implementation planning.
+- **If the result is empty, do not conclude "no connection exists."** An empty `connections list` is suspicious, not authoritative. Three things must hold before you treat it as real: (a) the key came from `registry search`, not memory; (b) the call used `--all-folders`; (c) a `--refresh` retry was still empty. Only then surface it in **Open Questions** so the user can create one while reviewing. Never ask the user a connection-creation question on an unverified empty result. See [impl.md](impl.md) for the platform-skill empty-result recovery path shared with implementation.
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `success`, `error` |
+
+The `error` port is the implicit error port shared with all action nodes — see [Implicit error port on action nodes](../../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Output Variables
+
+- `$vars.{nodeId}.output` — the connector response (structure depends on the operation)
+- `$vars.{nodeId}.error` — error details if the call fails
+
+## HTTP Fallback (Managed HTTP Request)
+
+When a connector exists but lacks the specific curated activity, use `core.action.http.v2` (Managed HTTP Request). This node proxies through the `uipath-uipath-http` connector and uses the **target connector's** IS connection for authentication — you supply the API URL and payload.
+
+> **Do NOT use individual connector HTTP request nodes** (e.g., `uipath.connector.<key>.http-request`). Always use the unified `core.action.http.v2` Managed HTTP Request node for non-curated API calls.
+
+> **Do NOT use `core.action.http` (v1) with `authenticationType: "connection"` for this.** The v1 node does not pass IS credentials at runtime. Always use `core.action.http.v2`.
+
+See [http/planning.md](../http/planning.md) for full selection heuristics and [http/impl.md](../http/impl.md) for configuration via `uip maestro flow node configure`.
+
+Note as `managed-http: <service> — <operation>` during planning.
+
+## Planning Annotation
+
+In the architectural plan, annotate connector nodes as:
+- `connector: <service-name>` with the intended operation (e.g., "connector: Jira — create issue")
+- If discovery found no connector, fall back to `core.action.http.v2` (manual mode) or flag the gap in Open Questions

package/skills/uipath-maestro-flow/references/author/references/plugins/connector-trigger/impl.md

@@ -0,0 +1,495 @@
+# Connector Trigger Nodes — Implementation
+
+How to configure connector trigger nodes: connection binding, enriched metadata, event parameter resolution, and trigger-specific `node configure` fields. This replaces the IS activity workflow (Steps 1-6 in [connector/impl.md](../connector/impl.md)) — trigger nodes have different metadata and configuration.
+
+> **This plugin covers two node families that share the same configuration mechanism:**
+>
+> - **Connector triggers** (`uipath.connector.trigger.<key>.<trigger>`) — start node; the event starts the flow. The default subject of every step below.
+> - **Wait for events** (`uipath.connector.event.<key>.<event>`) — a mid-flow event node; the flow pauses and waits for the event before continuing. Same connection binding, enriched metadata, event parameter resolution, filter trees, and `node configure` fields. Only the placement and node lifecycle differ. See [Wait for events](#wait-for-events-uipathconnectoreventkeyevent) for the deltas, then apply Steps 1-6 below unchanged.
+
+## Configuration Workflow
+
+Follow these steps for every IS trigger node.
+
+### Step 1 — Fetch a preliminary connection and query trigger objects
+
+Extract the connector key from the node type (`uipath.connector.trigger.<connector-key>.<trigger-name>`) and the operation name from the `registry get` response (`model.context[].operation`).
+
+**1a. Get any enabled connection** — needed as `--connection-id` for `triggers objects` below.
+
+Discovery call is **always**:
+
+```bash
+uip is connections list "<connector-key>" --all-folders --output json
+```
+
+`--all-folders` is mandatory. Without it the CLI returns the active folder only and hides connections in other folders the user can see. Plain `uip is connections list "<connector-key>"` is forbidden for discovery.
+
+> **MUST READ before any `uip is connections ...` call:** [/uipath:uipath-platform — connections.md](../../../../../../uipath-platform/references/integration-service/connections.md). Single source of truth for selection rules, BYOA filtering, empty-result recovery, ping verification.
+
+Pick any enabled connection (prefer `IsDefault: Yes`) and capture its `Id` for Step 1b.
+
+**1b. Query trigger objects** — **mandatory** for every trigger node. Do NOT skip:
+
+```bash
+uip is triggers objects "<connector-key>" "<OPERATION>" \
+  --connection-id "<id>" --output json
+```
+
+Save the response. It carries three pieces per event object that drive later steps:
+
+| Field | Drives | Meaning |
+|------|--------|---------|
+| `byoaConnection` | Step 1c | If `true`, only BYOA connections are valid for this event |
+| `isWebhookUrlVisible` | Step 6b | If `true`, retrieve and present the webhook URL |
+| **`parameters[]`** | Steps 3 & 4 | **Canonical** list of event-parameter input fields. Use exclusively; ignore `eventParameters.fields` from `flow registry get` (Step 2). |
+
+It may also include `design.textBlocks` with connector-specific user-facing instructions (e.g., "Add this URL to your Slack app's Event Subscriptions"). Surface that text verbatim when applicable — do not invent service-specific guidance.
+
+> `byoaConnection` and `isWebhookUrlVisible` are per event object, not per connector — some connectors require BYOA for some events but not others. `parameters[]` is per event object too: each operation has its own input fields.
+
+#### Reading `parameters[]`
+
+Each entry is one input field the user supplies when configuring the trigger (e.g., GitHub `repo`, Outlook `parentFolderId`, Slack `channelId`). For each:
+
+| Key | Use |
+|---|---|
+| `name` | Key inside the `--detail` bucket selected by `type` — see below |
+| `displayName` | Label when prompting the user for a missing value |
+| `dataType` | Value type (`string`, `number`, `boolean`, …) |
+| `required` | Drives Step 4's required-field check |
+| `reference` | Present → resolve to an ID in Step 3 (`uip is resources run list`) before configure |
+| `description` | Field hint — surface verbatim when prompting |
+| `design.position` | `"primary"` indicates a top-level input field; other positions are layout hints — safe to ignore for configure |
+| `type` | Bucket selector in Step 6's `--detail`: `"query"` → `queryParameters`, `"path"` → `pathParameters`, else → `eventParameters` |
+
+> **Source of truth:** `parameters[]` is populated for every connector. `flow registry get`'s `eventParameters.fields` derives from `triggers describe`'s `events.<operation>.required`/`.optional`, which several connectors do not emit. Full field semantics: [/uipath:uipath-platform — triggers.md — `parameters[]`](../../../../../../uipath-platform/references/integration-service/triggers.md#parameters--canonical-event-parameter-input-fields).
+
+### Step 1c — Select the final connection
+
+**If `byoaConnection: true`** — the Step 1a connection is not usable. Follow the BYOA selection workflow in [/uipath:uipath-platform — connections.md — For BYOA Connections](../../../../../../uipath-platform/references/integration-service/connections.md#for-byoa-connections-webhook-triggers) (filter with `--byoa`, `--refresh` retry, stop-and-ask if none exist).
+
+**If `byoaConnection: false`** — use the Step 1a connection. Verify health:
+
+```bash
+uip is connections ping "<connection-id>" --output json
+```
+
+### Step 2 — Get enriched trigger metadata
+
+`--connection-id` is **required** for trigger nodes. Without it, the command fails.
+
+```bash
+uip maestro flow registry get <trigger-node-type> --connection-id <connection-id> --output json
+```
+
+The response contains three trigger-specific sections:
+
+**`eventParameters.fields`** — non-authoritative. Often empty (see Step 1b). Iterate [`parameters[]`](#reading-parameters) from Step 1b in Steps 3 and 4 — do not iterate this block.
+
+Shape only — do not iterate:
+
+```json
+{
+  "eventParameters": {
+    "fields": [
+      {
+        "name": "parentFolderId",
+        "displayName": "Email folder",
+        "type": "string",
+        "required": true,
+        "reference": {
+          "objectName": "MailFolder",
+          "lookupValue": "id",
+          "lookupNames": ["displayName"],
+          "path": "/MailFolders"
+        }
+      }
+    ]
+  }
+}
+```
+
+**`filterFields`** — fields used to narrow *which* events fire the trigger (e.g., only emails from a specific sender). These are optional filter criteria and are passed as a structured tree in `--detail.filter` (see [Filter Trees](#filter-trees)).
+
+```json
+{
+  "filterFields": {
+    "fields": [
+      {
+        "name": "fromAddress",
+        "displayName": "From address",
+        "type": "string",
+        "required": false
+      }
+    ]
+  }
+}
+```
+
+**`outputResponseDefinition`** — the event payload schema (all fields the trigger outputs when it fires). **Save this** — you need it in Step 4b to know the exact field paths for downstream `$vars` expressions (e.g., `$vars.{nodeId}.output.text`, `$vars.{nodeId}.output.channel`). Do not guess output field names.
+
+**`eventMode`** — `"webhooks"` or `"polling"`.
+
+The response (which becomes the `definitions[]` entry verbatim) includes `model.context` with:
+- `connectorKey` — the connector identifier
+- `operation` — the event operation name (e.g., `"EMAIL_RECEIVED"`, `"ISSUE_CREATED"`)
+- `objectName` — the IS object (e.g., `"Message"`, `"Issue"`)
+
+These live in the **definition**, not on the node instance. The instance carries only `inputs` (event filter fields) and `outputs`.
+
+### Step 3 — Resolve reference fields in event parameters
+
+Iterate `parameters[]` (Step 1b). For each entry with a `reference` key, run an ID lookup — same mechanism as IS activity nodes.
+
+> **Resolve every reference field freshly, against the current `--connection-id`, immediately before `node configure` (Step 6)** — even if you think you already know the ID from a previous flow. Reference IDs are connection-scoped and reused values fault silently at runtime. See [Reference IDs Are Connection-Scoped (CRITICAL)](../../../../../../uipath-platform/references/integration-service/reference-resolution.md#reference-ids-are-connection-scoped-critical) for the full mechanism and failure mode, and the top-level Anti-Patterns in [SKILL.md](../../../../../SKILL.md).
+
+```bash
+# Example: resolve Outlook mail folder "Inbox" to its ID
+uip is resources run list "<connector-key>" "<reference.objectName>" \
+  --connection-id "<id>" --output json
+```
+
+The `<id>` in `--connection-id "<id>"` MUST be the connection bound to **this** flow (the final connection from Step 1c), not any other connection you've used in another flow. Use the resolved IDs — from this very `run list` call — in the trigger's event parameter configuration.
+
+> **Paginate when looking up by name.** Use `Data.Pagination.HasMore` / `NextPageToken` with `--query "nextPage=<token>"`. Short-circuit on match. Do NOT conclude "not found" until `HasMore` is `"false"`. See [resources.md#pagination](../../../../../../uipath-platform/references/integration-service/resources.md#pagination).
+
+**Read [/uipath:uipath-platform — Integration Service — resources.md](../../../../../../uipath-platform/references/integration-service/resources.md) for the full reference-resolution workflow** (pagination, describe failures, fallbacks).
+
+### Step 4 — Validate required event parameters
+
+Check every entry in `parameters[]` (Step 1b) where `required: true`. All required event parameters must have values before building the flow.
+
+1. Collect all required entries from `parameters[]`
+2. For each, check if the user's prompt provides a value
+3. If any required field is missing, **ask the user** — list the missing fields with their `displayName` (and `description` if useful). Free-form input is appropriate when the value space is open-ended; when a finite set of sensible values exists, present them via `AskUserQuestion` per the dropdown rule in [SKILL.md](../../../../../SKILL.md).
+4. Only proceed after all required event parameters are resolved
+
+> Step 6 buckets each resolved value into `eventParameters`, `queryParameters`, or `pathParameters` based on the entry's `type` — see Step 6's `--detail` table.
+
+### Step 4b — Map trigger output fields for downstream nodes
+
+Before wiring downstream nodes, check `outputResponseDefinition` from Step 2 to know the exact field names available in `$vars.{triggerId}.output`. Do NOT guess field names — different triggers output different schemas.
+
+Each trigger type has a different output schema — field names like `.text`, `.subject`, or `.body.content` vary by connector. Use the actual field names from `outputResponseDefinition` when writing expressions in downstream nodes.
+
+### Step 5 — Replace the manual trigger with the connector trigger node
+
+Follow the [CLI: Replace manual trigger with connector trigger](../../editing-operations-cli.md#replace-manual-trigger-with-connector-trigger) procedure. The CLI handles edge cleanup, orphaned definition removal, and `variables.nodes` regeneration automatically. Note the generated node ID from the `node add` response — you need it for Step 6.
+
+### Step 6 — Configure the trigger node
+
+**Read the `--detail` field table below before calling `node configure`.** The fields and types are strict — unknown keys or wrong types cause validation errors. Do not guess field names from other node types (e.g., activity nodes use `method`/`endpoint`/`bodyParameters`; triggers use `eventMode`/`eventParameters`/`filter`).
+
+Use `node configure` with trigger-specific `--detail` fields:
+
+```bash
+uip maestro flow node configure <PROJECT>.flow <triggerId> --output json --detail '{
+  "connectionId": "<CONNECTION_ID>",
+  "folderKey": "<FOLDER_KEY>",
+  "eventMode": "<EVENT_MODE>",
+  "eventParameters": { "<paramName>": "<RESOLVED_VALUE>" },
+  "filter": {
+    "groupOperator": 0,
+    "index": 0,
+    "filters": [
+      {
+        "id": "subject",
+        "operator": "Contains",
+        "value": { "value": "urgent", "rawString": "\"urgent\"", "isLiteral": true }
+      }
+    ]
+  }
+}'
+```
+
+**`--detail` fields for triggers:**
+
+| Field | Required | Description |
+|---|---|---|
+| `connectionId` | Yes | Connection UUID from Step 1c (the final connection — BYOA if required) |
+| `folderKey` | Yes | Orchestrator folder key for the connection |
+| `eventMode` | Yes | `"webhooks"` or `"polling"` — from `registry get` response |
+| `eventParameters`, `queryParameters`, `pathParameters` | No | JSON objects of resolved values from Steps 3-4. Bucket each `parameters[]` entry by its `type`: `"query"` → `queryParameters` (e.g. GitHub `{"repo":"cli"}`, Outlook `{"sharedMailboxAddress":"..."}`), `"path"` → `pathParameters` (e.g. GitHub `{"owner":"uipath"}`), otherwise → `eventParameters`. Within each bucket, the key is `parameters[].name`. Each must be a JSON object. |
+| `filter` | No | Structured filter tree — see [Filter Trees](#filter-trees) below. Omit to trigger on all events |
+
+The CLI computes the runtime JMESPath `filterExpression` from `filter` automatically and persists both into the workflow so Studio Web can re-open the trigger without losing the filter configuration. **Do not pass `filterExpression` directly — the validator rejects it.**
+The command populates `inputs.detail` (including the internal `configuration` blob with the `filter` tree and combined `filterExpression`) and creates workflow-level connection bindings.
+
+> **Shell quoting tip:** For complex `--detail` JSON, write it to a temp file: `uip maestro flow node configure <file> <nodeId> --detail "$(cat /tmp/detail.json)" --output json`
+
+### Step 6b — Retrieve and display webhook URL (webhooks only)
+
+Applies when `eventMode` is `"webhooks"`, regardless of `byoaConnection`.
+
+> **Guard:** If the trigger object's `isWebhookUrlVisible` is `false` (from Step 1b), skip this step — the connector manages webhook registration automatically and does not expose a URL. If you do not have `triggers objects` output, you skipped Step 1b — go back.
+
+Follow [/uipath:uipath-platform — triggers.md — Webhook URL Retrieval](../../../../../../uipath-platform/references/integration-service/triggers.md#webhook-url-retrieval) for the exact commands (`uip is connections list` → `ElementInstanceId` → `uip is webhooks config`).
+
+**Presenting the URL:** If the Step 1b `triggers objects` response included `design.textBlocks`, use that text verbatim (substituting `{webhookUrl}`) — it carries connector-specific registration instructions. Otherwise, use a generic message instructing the user to register the URL in their external service's app settings (e.g., Slack Event Subscriptions, Salesforce Outbound Messages). The trigger will not fire until the URL is registered and verified.
+
+**On failure:** if `ElementInstanceId` is empty, the connection is the wrong type — verify the `byoaConnection` flag from Step 1b and switch to a BYOA connection if required. If `webhooks config` itself fails, ping the connection (`uip is connections ping`) and re-authenticate via `uip is connections edit` if unhealthy.
+
+---
+
+## Wait for events (`uipath.connector.event.<key>.<event>`)
+
+A **Wait for events** node waits for an external event **mid-flow** instead of starting the flow ("wait for the approval reply", "wait until the Jira issue is Done"). Same connector event as a trigger — identical `eventParameters`, `filterFields`, `outputResponseDefinition`, `eventMode`, connection binding, reference resolution, filter trees. Apply Steps 1-6 above unchanged; only the deltas below differ.
+
+| Aspect | Connector **trigger** | **Wait for events** (mid-flow) |
+|---|---|---|
+| Node type | `uipath.connector.trigger.<key>.<trigger>` | `uipath.connector.event.<key>.<event>` |
+| Position | Start node — replaces the manual trigger | Mid-flow — has an `input` port |
+| Add | Step 5: [replace the manual trigger](../../editing-operations-cli.md#replace-manual-trigger-with-connector-trigger) | `node add` like an action node; do **NOT** remove the start node |
+| Ports | in: — · out: `output` | in: `input` · out: `output`, `error` |
+| Start trigger | Is the flow's trigger | Not a trigger — flow still needs its own start trigger |
+| Discovery search | `... search "<svc>" trigger` | `... search "<svc>" event` |
+| Config (Steps 1-4, 6) | Identical | Identical |
+
+Add and wire:
+
+```bash
+uip maestro flow node add <PROJECT>.flow uipath.connector.event.<key>.<event> \
+  --label "<LABEL>" --position 400,144 --output json
+```
+
+Wire an incoming edge into `input` and an outgoing edge from `output` per [editing-operations-json.md — Insert a node between two existing nodes](../../editing-operations-json.md#insert-a-node-between-two-existing-nodes). Downstream reads `$vars.{eventNodeId}.output` (payload) and `$vars.{eventNodeId}.error`; wire `error` to survive an event-wait failure.
+
+> **The flow still needs a separate start trigger.** A mid-flow event node does **not** start the flow. Do not remove `core.trigger.manual`/`scheduled` or the connector trigger that begins the flow.
+
+---
+
+## Filter Trees
+
+Filters are authored as a **structured tree**, not a string expression. The CLI compiles the tree into a JMESPath `filterExpression` using the same logic Studio Web does, and writes both forms into the flow so the trigger round-trips cleanly when re-opened in SW.
+
+### Tree shape
+
+```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>",        // from filterFields.fields[].name
+      "operator": "<Operator>",   // see operator table below
+      "value": {
+        "value": <typed value>,   // string / number / boolean / ISO-8601 date-time
+        "rawString": "\"...\"",   // verbatim user-entered text (with quotes for strings)
+        "isLiteral": true         // literals only — expression values are not supported
+      }
+    }
+  ],
+  "groups": []                    // optional: nested subgroups (same shape as root)
+}
+```
+
+A no-op filter — used when the user wants all events to fire the trigger — is `null` or `{"groupOperator": null, "index": 0, "filters": []}`. Prefer **omitting** the `filter` field entirely.
+
+### Supported operators
+
+| Operator | Meaning | Typical field types |
+|---|---|---|
+| `Equals` / `NotEquals` | Exact (in)equality | string, number, boolean |
+| `LessThan` / `LessThanOrEqual` / `GreaterThan` / `GreaterThanOrEqual` | Numeric comparison | number, integer |
+| `Contains` / `NotContains` | Substring match | string |
+| `StartsWith` / `NotStartsWith` / `EndsWith` / `NotEndsWith` | Prefix / suffix match | string |
+| `IsEmpty` / `IsNotEmpty` | Value is / is not empty string | string (no `value` needed) |
+| `Is` / `IsNot` | Boolean is true / false | boolean (no `value` needed) |
+| `In` / `NotIn` / `IsOneOf` / `IsNotOneOf` | Membership — pass comma-separated values in `value.value` | string, number |
+| `Before` / `BeforeOrEqual` / `After` / `AfterOrEqual` / `DateTimeEquals` / `DateTimeNotEqual` | Date-time comparison (ISO-8601 strings) | date-time |
+
+### Examples
+
+**Emails containing "urgent" in the subject:**
+
+```json
+{
+  "groupOperator": 0,
+  "index": 0,
+  "filters": [
+    { "id": "subject", "operator": "Contains",
+      "value": { "value": "urgent", "rawString": "\"urgent\"", "isLiteral": true } }
+  ]
+}
+```
+
+**Emails from a specific sender AND subject contains "good day":**
+
+```json
+{
+  "groupOperator": 0,
+  "index": 0,
+  "filters": [
+    { "id": "from", "operator": "Equals",
+      "value": { "value": "boss@example.com", "rawString": "\"boss@example.com\"", "isLiteral": true } },
+    { "id": "subject", "operator": "Contains",
+      "value": { "value": "good day", "rawString": "\"good day\"", "isLiteral": true } }
+  ]
+}
+```
+
+**Multiple senders (OR) nested inside an outer AND with a subject match:**
+
+```json
+{
+  "groupOperator": 0,
+  "index": 0,
+  "filters": [
+    { "id": "subject", "operator": "Contains",
+      "value": { "value": "urgent", "rawString": "\"urgent\"", "isLiteral": true } }
+  ],
+  "groups": [
+    {
+      "groupOperator": 1,
+      "index": 1,
+      "filters": [
+        { "id": "from", "operator": "Equals",
+          "value": { "value": "a@ex.com", "rawString": "\"a@ex.com\"", "isLiteral": true } },
+        { "id": "from", "operator": "Equals",
+          "value": { "value": "b@ex.com", "rawString": "\"b@ex.com\"", "isLiteral": true } }
+      ]
+    }
+  ]
+}
+```
+
+### How to build a filter tree from `filterFields`
+
+1. Run `flow registry get` with `--connection-id` (Step 2) and read the `filterFields.fields` array. Each entry has a `name` (use as the leaf `id`), a `type` (drives operator selection), and an optional `description`.
+
+Then follow [/uipath:uipath-platform — triggers.md > Building Filter Trees from filterFields](../../../../../../uipath-platform/references/integration-service/triggers.md#building-filter-trees-from-filterfields) for the rest of the procedure (operator selection, leaf composition, value wrapping), the mandatory-filter contract (connector-mandated values like Gmail folder go on `eventParameters`, never the freeform `filter` tree), and array-shaped field handling.
+
+### What NOT to generate
+
+| Invalid input | Why it fails | Valid replacement |
+|---|---|---|
+| `"filterExpression": "(contains(subject, 'x'))"` | Legacy format — the CLI now rejects `filterExpression` as an input field (see MST-8802). It is *only* an output in the generated `.flow`. | Build a `filter` tree with a `Contains` leaf. |
+| `"filter": "(subject == 'x')"` | `filter` must be an object, not a string. | Structured tree with `filters: [...]`. |
+| `{ "id": "fields.subject", ... }` | `fields.` prefix — use the bare field name from `filterFields.fields[].name`. | `{ "id": "subject", ... }` |
+| `{ "id": "subject", "operator": "contains", ... }` | Operator is case-sensitive — use PascalCase. | `"operator": "Contains"` |
+| `{ "value": "urgent" }` on a leaf | Bare string — must be wrapped in the `WorkflowValue` object. | `{ "value": { "value": "urgent", "rawString": "\"urgent\"", "isLiteral": true } }` |
+| `{ "isLiteral": false, "value": "${var}" }` | Expression values are not yet supported by the CLI port. | Resolve the value first, then pass it as a literal. |
+| Adding a freeform leaf for a connector-mandated field (e.g. Gmail folder, Slack channelId) | Mandatory filters derived from connector event metadata are emitted automatically by the CLI from `eventParameters` — duplicating them in the freeform tree double-applies the clause. | Set the value through `eventParameters` only; the CLI AND-joins the mandatory JMES clause into the top-level `inputs.detail.filterExpression` (matching SW's `combinedFilterExpression`). It is *not* persisted on `essentialConfiguration` — SW classifies it optional and rebuilds it from input field values on restore. |
+
+---
+
+## Bindings
+
+Trigger nodes require more binding resources than activity nodes: `Connection` + `EventTrigger` + `Property` resources. **`node configure` and the packaging pipeline handle all of these automatically:**
+
+- **Connection bindings** — created in the `.flow` file by `node configure` (Step 6)
+- **EventTrigger + Property bindings** — generated into `bindings_v2.json` during `flow debug` or packaging from the trigger node's `inputs.detail`
+
+You do **not** need to manually create or edit `bindings_v2.json` for trigger nodes.
+
+---
+
+## CLI Commands
+
+```bash
+# Discovery
+uip maestro flow registry search trigger --output json               # find trigger node types
+uip maestro flow registry pull --force                                # refresh registry (requires login)
+
+# Enriched trigger metadata (--connection-id REQUIRED)
+uip maestro flow registry get <trigger-node-type> --connection-id <connection-id> --output json
+
+# Node lifecycle
+uip maestro flow node remove <PROJECT>.flow start --output json       # remove manual trigger
+uip maestro flow node add <PROJECT>.flow <trigger-node-type> --label "<LABEL>" --position 200,144 --output json
+uip maestro flow node configure <PROJECT>.flow <nodeId> --detail '<TRIGGER_DETAIL_JSON>' --output json
+
+# Trigger object metadata (MANDATORY — Step 1b)
+uip is triggers objects "<connector-key>" "<operation>" --connection-id "<id>" --output json
+uip is triggers describe "<connector-key>" "<operation>" "<objectName>" --connection-id "<id>" --output json
+
+# Connections — see /uipath:uipath-platform — connections.md for selection rules (Native, BYOA, --refresh)
+uip is connections list "<connector-key>" --all-folders --output json         # discover connections (--all-folders is mandatory)
+uip is connections list "<connector-key>" --byoa --all-folders --output json  # BYOA only (Step 1c)
+uip is connections ping "<connection-id>" --output json               # verify health
+
+# Reference resolution (same as IS activity)
+uip is resources run list "<connector-key>" "<resource>" \
+  --connection-id "<id>" --output json
+
+# Webhook URL retrieval — see /uipath:uipath-platform — triggers.md (Step 6b, webhooks only)
+uip is webhooks config "<connector-key>" \
+  --connection-id "<connection-guid>" \
+  --element-instance-id <number> --output json
+```
+
+---
+
+## Testing Trigger Flows
+
+`uip maestro flow debug` works with trigger-based flows. Debug does **not** wait for a live event — it **pulls the most recent matching event** from the connector's lookback window and executes immediately.
+
+### How debug works for triggers
+
+1. Debug calls the connector's `/events/debug` endpoint with `maxResults=5` and a `startDate` (default: 1 hour ago)
+2. The connector returns up to 5 matching events from that window, sorted most-recent-first
+3. The runtime uses `FilterMatches[0]` (the most recent match) as the trigger input
+4. The flow executes immediately with that event data
+5. If **no matching events** exist in the lookback window, debug fails with error code `3005` (TriggerNoMatches)
+
+```bash
+uip maestro flow debug . --output json
+# → Fetches most recent matching event from the past ~1 hour
+# → Flow executes immediately with that event data
+```
+
+### Polling vs webhook triggers in debug
+
+| Trigger mode | Debug support | Behavior |
+|---|---|---|
+| `polling` | Supported | Pulls recent events via debug API, executes immediately |
+| `webhooks` | **Not supported** | Webhook triggers cannot be tested in Studio debug mode — debug requires Orchestrator |
+
+> **If the trigger uses `webhooks` event mode**, tell the user that debug is not available for webhook triggers. They must deploy to Orchestrator and test with a real webhook event.
+
+### Key differences from manual-trigger debug
+
+| Aspect | Manual trigger | Connector trigger (polling) |
+|---|---|---|
+| Execution start | Immediate with user-provided inputs | Immediate with most recent matching event |
+| User action needed | Provide input values | Ensure a matching event exists in the past ~1 hour |
+| Failure mode | Missing required inputs | No matching events in lookback window (error 3005) |
+
+### Pre-debug checklist
+
+1. **Verify the connection is healthy** — `uip is connections ping "<id>"`
+2. **Confirm a matching event exists** — the user should have produced the event (e.g., sent an email, created a Jira issue) within the past hour
+3. **Check event mode** — if `webhooks`, debug is not supported; inform the user
+
+---
+
+## Debug
+
+### Common Errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `Trigger nodes require --connection-id` | Ran `registry get` without `--connection-id` | Re-run with `--connection-id <id>` — required for all trigger nodes |
+| No trigger nodes in registry | Not authenticated or registry not pulled | Run `uip login` then `uip maestro flow registry pull --force` |
+| Connection not found in bindings | `node configure` not run or connection expired | Re-run `node configure` with valid `connectionId` and `folderKey` |
+| Event parameter missing at runtime | Required event parameter not configured | Re-run `uip is triggers objects` (Step 1b). For each `parameters[]` entry with `required: true`, include under `eventParameters` in `--detail`. |
+| `filterExpression is derived from the filter tree and cannot be provided directly` | Passed `filterExpression` string instead of a `filter` tree | Build a structured `filter` tree — see [Filter Trees](#filter-trees) |
+| `Filter references field '<name>' which is not present in trigger metadata` | Leaf `id` does not match any `filterFields.fields[].name` | Re-run `registry get` and use a valid field name |
+| Trigger not firing | Event parameters point to wrong resource (e.g., wrong folder ID) | Re-resolve reference fields with `uip is resources run list` |
+| Trigger faults immediately with no visible error after a clean build | Event parameter uses a reference ID scoped to a **different** connection (common when copying from a prior flow in the same session — e.g., a `parentFolderId` for mailbox A pasted into a trigger bound to mailbox B's connection) | Re-run `uip is resources run list "<connector-key>" "<objectName>" --connection-id <CURRENT_CONNECTION_ID>`, extract the fresh ID, update `eventParameters` in `--detail`, re-run `node configure`, re-debug. See Step 3 and the top-level Anti-Pattern on reference-ID reuse in [SKILL.md](../../../../../SKILL.md). |
+| Definition's `model.context` missing operation | Definition not copied correctly, or node added before registry pull | Re-run `uip maestro flow registry pull --force`, then verify the `definitions[]` entry contains `model.context` with `connectorKey`/`operation`/`objectName` as returned by `registry get` |
+| Trigger faults at runtime with webhook-related error | Standard (non-BYOA) connection used for a trigger that requires `byoaConnection: true` | Run `uip is triggers objects` (Step 1b) to check `byoaConnection` flag, then switch to a BYOA connection with `uip is connections list "<connector-key>" --byoa --output json`. If no BYOA connections exist, user must create one. |
+| `connections list` returns empty but connections exist in the IS portal | CLI is using cached connection data that is stale | Retry with `--refresh` flag: `uip is connections list "<connector-key>" --refresh --output json` |
+| `ElementInstanceId` is empty on the selected connection | Connection is not a BYOA connection, or connector does not support webhooks on this connection type | Verify the trigger requires BYOA (Step 1b `byoaConnection` flag). If `true`, switch to a BYOA connection. |
+
+### Debug Tips
+
+1. **Always verify the connection is healthy** before debugging trigger issues — run `uip is connections ping "<id>"`
+2. **`flow validate` does NOT catch trigger-specific issues** — missing event parameters, wrong reference IDs, and expired connections are caught only at runtime
+3. **Event parameters with `reference` objects** need resolved IDs, not display names — same as IS activity fields
+4. **Filters are optional** — omit `filter` from `--detail` if the user wants all events to trigger the flow. Do not invent an "empty" expression.
+5. **Bindings are auto-managed** — `node configure` creates flow-level bindings; `flow debug`/packaging generates `bindings_v2.json` from them
+6. **Use `uip maestro flow node remove` to remove the manual trigger** — do NOT use `Edit` to delete the start node. The CLI automatically removes associated edges, orphaned definitions, and regenerates `variables.nodes`. Hand-editing skips these cleanup steps and can leave orphaned references.
+7. **Check `outputResponseDefinition` before writing downstream expressions** — trigger output field names vary by connector. Do not assume field names like `.text` or `.subject` — verify from the enriched `registry get` response (Step 2)
+8. **Validate filter field names against `filterFields`** — only field names returned in `filterFields.fields[].name` are valid leaf `id`s in the filter tree. The CLI rejects trees that reference unknown fields at configure time, so guessing will surface as an `InvalidDetailError` rather than a silent runtime no-match.