@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,186 @@
+# 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 | **Non-catalog activity generation** | A connector exists but lacks the curated activity, **and the connector reports `V4Compatible`** — uses the connector's IS connection for auth. Invoke the `uipath-platform` skill's activity generation (sanctioned exception to [SKILL.md rule #4](../../../../SKILL.md#critical-rules-universal) — no user prompt once the gap and flag are confirmed), then author the node per [impl-inline.md](impl-inline.md). Never skip to Tier 3 on a `V4Compatible` connector |
+| 3 | **Managed HTTP Request** (`core.action.http.v2`) | A connector exists but lacks the curated activity, and does **not** report `V4Compatible` — uses the connector's IS connection for auth |
+| 4 | **Managed HTTP Request — manual mode** (`core.action.http.v2`) | No connector exists — you provide the full URL manually |
+| 5 | **RPA workflow** | Target system has no API at all (legacy desktop apps, terminals) |
+
+**Tiers 2 and 3 answer the same question — the connector is there, the activity is
+not. Establish the gap FIRST, the same way you always have**
+([Sanity-check before deciding "no connector activity exists"](#sanity-check-before-deciding-no-connector-activity-exists)):
+`registry search`, and if it returns triggers but no activities, `registry pull
+--force` and search again. Only when the second search still shows no activity is
+the gap real.
+
+**Then** one connector metadata call decides which fallback:
+
+```bash
+uip is connectors metadata <connector-key> --output json
+```
+
+Read `Data[0].Flags.V4Compatible`:
+
+| value | route |
+|---|---|
+| `true` | **Tier 2** — generate a non-catalog activity |
+| `false`, or the key is **absent** | **Tier 3** — Managed HTTP Request |
+
+The key is PascalCase in CLI output: `--output-filter "[0].Flags.v4Compatible"` (lowercase `v`) returns `Data: []`, which reads as "flag absent" and misroutes a Tier 2 connector to Managed HTTP — filter on `Flags` or `Flags.V4Compatible`. Test for the value, not for the presence of `Flags`. `Flags` is `{}` on most
+connectors rather than missing, so `Flags && …` passes while
+`Flags.V4Compatible` is `undefined`. Measured: `uipath-salesforce-slack`
+returns `{"V4Compatible": true}`; `uipath-atlassian-jira`,
+`uipath-microsoft-teams` and `uipath-google-drive` all return `{}`.
+
+The flag is a **capability hint for choosing a node type, not an authorization
+decision** — it says the connector can host a generated activity, not that the
+caller may call anything. Auth is still the connector's IS connection, enforced
+at runtime.
+
+### 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, falling through is legitimate — to Tier 2 or Tier 3 depending on `V4Compatible`, as above. 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.
+
+- Filter to `State: Enabled`, then record the connection ID for implementation planning. `IsDefault: Yes` is a tenant-wide preference, not a suitability signal.
+- Record which connection a reference lookup resolved against. Before concluding a user-supplied value does not exist, see [impl.md — Step 4](impl.md#step-4--resolve-reference-fields).
+- **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 **and does not
+report `V4Compatible`** (Tier 3 — check the connector metadata first, see
+[Decision Order](#decision-order)), 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.
+
+If the connector *does* report `V4Compatible`, prefer Tier 2 instead: a
+generated non-catalog activity keeps the operation as a first-class activity
+node rather than a hand-supplied URL. The activity comes from the
+`uipath-platform` skill's [activity-generation.md](../../../../../uipath-platform/references/integration-service/activity-generation.md).
+Invoking that skill for this purpose is an explicit exception to
+[SKILL.md rule #4](../../../../SKILL.md#critical-rules-universal): once the
+gap is established and `V4Compatible` is `true`, invoke it directly rather
+than stopping to ask — but follow its guide, do not reimplement its
+`uip is activities` steps here. The node is then authored per
+[impl-inline.md](impl-inline.md). Fall back to this Tier 3 Managed HTTP path
+on a `V4Compatible` connector only when the `uipath-platform` skill is
+unavailable in the session, and say so in the final report.
+
+> **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