@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,166 @@
+# HITL Node — Planning
+
+The flow needs to pause for a human to review, approve, or fill in data. Two node types serve this need — choose based on form complexity and whether an app already exists.
+
+---
+
+## Which HITL Node to Use
+
+| Use case | Node type | Form source |
+| --- | --- | --- |
+| Inline form designed right now (fields + outcomes defined in the flow) | `uipath.human-in-the-loop.quick-form` | Schema embedded in node inputs — no app needed |
+| Existing coded app or Action Center app | `uipath.human-in-the-loop.coded-action-app` | Deployed app from Orchestrator |
+
+**Prefer `uipath.human-in-the-loop.quick-form`** for new flows. It is an OOTB node — no registry discovery, no app publishing, no tenant dependency.
+
+---
+
+## Option 1 — `uipath.human-in-the-loop.quick-form` (Inline Schema — OOTB)
+
+Node type: `uipath.human-in-the-loop.quick-form`
+Available: always — no `uip login` or registry pull required.
+
+### When to Select
+
+| Situation | Select? |
+| --- | --- |
+| Manager approval before processing | Yes |
+| Human reviews extracted data before submission | Yes |
+| Human resolves exceptions the automation cannot handle | Yes |
+| Need a quick form with specific fields and outcomes | Yes |
+| Existing coded/Action Center app should be used | No — use Option 2 |
+| Fully automated processing, no human involvement | No |
+| The user wants to **see** a value the flow produced | Only if a human will open the task — see below |
+
+**A HITL node blocks until a human completes its task, so place one only where a human actually will.** The task appears in Action Center; if it has no assignee, or the run is unattended (a schedule, a `flow debug`, an eval), nobody opens it and the flow never reaches its End node. The instance stays `Running` until the caller's timeout, with no output. Every outcome port can be wired correctly and this still happens, so it does not present as the unwired-port failure below.
+
+**"Show me the result" does not by itself mean a form.** The mechanisms differ in who can consume them, so ask what *seeing it* means before choosing:
+
+| Mechanism | Reaches | Completes unattended |
+| --- | --- | --- |
+| HITL form | a person who opens Action Center | No — blocks until submitted |
+| Message to a channel or mailbox (connector node) | a person wherever they already are | Yes |
+| `out` variable mapped on the End node | whoever or whatever invoked the flow | Yes |
+
+With no user to ask, pick one that terminates unattended and record which you chose and why. Do not reach for a form because the request said "display" — that word describes the goal, not the node.
+
+### Ports
+
+| Input port | Output port(s) |
+| --- | --- |
+| `input` | one per outcome — `outcome-<outcome.id>`, derived verbatim from `inputs.schema.outcomes[].id` |
+
+**Every outcome gets its own port — wire one edge per outcome, not a single shared port.** A schema with `outcomes: [Approve, Reject]` (ids `approve`, `reject`) produces two ports, `outcome-approve` and `outcome-reject`; each needs its own edge. Every outcome needs a non-empty string `id` — one without gets no handle at all, so an edge drawn to a guessed port name is a no-op, not a working branch. A node with any outcome port left unwired blocks the flow indefinitely on that branch.
+
+> **`outcome-completed` is the port for a zero-outcome node, or for a real outcome whose `id` is literally `completed`.** It is an ordinary string, not a reserved one, so it can be a genuine outcome port. The instant `inputs.schema.outcomes` has one or more entries with a different `id` — including the shipped default `Submit` (id `submit`) — its port becomes `outcome-submit`, not `outcome-completed`. Never wire `outcome-completed` standing in for several different outcomes.
+
+### Output Variables
+
+- `$vars.{nodeId}.output` — object containing all output and inOut fields the human filled in
+- `$vars.{nodeId}.output.{fieldName}` — individual field value
+- `$vars.{nodeId}.status` — selected outcome's action value (`"Continue"` or `"End"`)
+
+### Schema Design
+
+The schema defines what the human sees and provides. Three field categories:
+
+| Category | Human can… | Use for |
+| --- | --- | --- |
+| `inputs` | Read only | Context the human needs to decide |
+| `outputs` | Write | Data the automation needs back |
+| `inOuts` | Read + modify | Fields the human can see and optionally correct |
+
+Outcomes are the action buttons (e.g., Approve/Reject). First outcome is primary.
+
+**In the architectural plan**, describe the schema:
+```
+inputs:   [invoiceId (string), amount (number)]
+outputs:  [decision (string, required)]
+outcomes: [Approve, Reject]
+priority: Low
+```
+
+Full JSON format and conversion examples: see [`uipath-human-in-the-loop` skill](../../../../../uipath-human-in-the-loop/references/hitl-node-quickform.md).
+
+> **Note:** Skills are self-contained — cross-skill references are for documentation context only. The agent uses the `uipath-human-in-the-loop` skill to implement HITL nodes; this planning guide is for topology selection only.
+
+### Wiring Pattern
+
+```
+[Upstream] -> [HITL] ->|outcome-approve| [Continue]
+                ->|outcome-reject| [End]
+```
+
+Each outcome branches directly off its own handle — no separate Decision node needed to re-derive the branch from `$vars.{nodeId}.status`.
+
+### Common Topology Patterns
+
+**Approval gate:**
+```
+Trigger -> Fetch Data -> HITL (review, outcomes: Approve/Reject) ->
+  outcome-approve: Script (process) -> End
+  outcome-reject: Script (log rejection) -> End
+```
+
+**Exception escalation:**
+```
+Trigger -> Process -> Decision (confidence ok?) ->
+  true: Continue -> End
+  false: HITL (exception review, outcomes: Retry/Escalate) ->
+    outcome-retry: Script (retry with human input) -> End
+    outcome-escalate: End
+```
+
+**Do not insert a Decision node after a HITL node to re-branch on outcome.** Each outcome already has its own wired handle — that handle IS the branch point. Reach for a Decision node only where the branch is on something other than the HITL outcome itself (e.g., the confidence check above, which runs before any HITL node).
+
+### Planning Annotation
+
+In the node table:
+```
+| hitlReview | Invoice Review | human-task | uipath.human-in-the-loop.quick-form | inputs: [invoiceId, amount] outputs: [decision] outcomes: [Approve, Reject] | output, status |
+```
+
+---
+
+## Option 2 — `uipath.core.human-task.{key}` (App-Based)
+
+Node type: `uipath.core.human-task.{key}`
+Available: tenant-specific resource — requires `uip login` + `uip maestro flow registry pull`.
+
+### When to Select
+
+Use when there is an existing coded app or Action Center app that should be the task form.
+
+### Ports
+
+| Input port | Output port |
+| --- | --- |
+| `input` | `output` |
+
+### Output Variables
+
+- `$vars.{nodeId}.output` — form data submitted by the user
+- `$vars.{nodeId}.error` — error details if execution fails
+
+### Discovery
+
+**Published (tenant registry):**
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.human-task" --output json
+```
+
+**In-solution (local, no login required):**
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+Run from inside the flow project directory. Discovers sibling projects in the same `.uipx` solution.
+
+### Planning Annotation
+
+- If the app exists: note as `resource: <name> (human-task)`
+- If it does not exist: note as `[CREATE NEW] <description>` with skill `uipath-coded-apps`, use `core.logic.mock` placeholder

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

@@ -0,0 +1,86 @@
+# HTTP Request Node — Connector Mode
+
+Use this walkthrough when the target service has an IS connector and you want managed auth (OAuth / API key) handled by an existing IS connection.
+
+**Prerequisite:** a healthy IS connection for the target connector. Step 2 verifies this. If none exists, propose manual mode as the fallback and confirm the switch with the user before finalizing — do not switch modes without that confirmation.
+
+Before starting, read [impl.md](impl.md) for the node type, registry validation, and the "always use `node configure`" rule. Follow Steps 1–5 in order.
+
+## Step 1 — Add the node
+
+```bash
+uip maestro flow node add <ProjectName>.flow core.action.http.v2 \
+  --label "<HTTP node label>" --output json
+```
+
+> **Inside a loop body?** Add `--parent <LOOP_NODE_ID>` to set `parentId`. Without it, the node runs outside the loop context and outputs are null. See [loop/impl.md](../loop/impl.md).
+
+The CLI copies the manifest into `definitions[]`, adds the node instance, registers `variables.nodes`, and inserts a `layout.nodes` placeholder — byte-for-byte from the registry. Save the returned `<nodeId>` — Steps 2 and 3 reuse it. Leave `inputs` empty; Step 3 populates `inputs.detail`. Do not hand-author the definition — see [impl.md — Add the node](impl.md#add-the-node).
+
+## Step 2 — Identify target connection
+
+**Connector mode only works if the connector supports the HTTP request activity** — verify by running `uip is connectors get "<target-connector-key>"` and checking the `HasHttpRequest` flag. If the flag is false, **STOP** — a connection cannot help. Use the recovery question below (switch to manual mode / skip / something else; the create-a-connection option does not apply) and do not switch modes without confirmation.
+
+```bash
+uip is connections list "<target-connector-key>" --all-folders --output json
+```
+
+`--all-folders` is mandatory for discovery. Selection rules, empty-result recovery, and ping verification live in the platform skill — do not duplicate them here.
+
+> **MUST READ before any `uip is connections ...` call:** [/uipath:uipath-platform — connections.md](../../../../../uipath-platform/references/integration-service/connections.md).
+
+Record the chosen connection's `Id` and `FolderKey` — Step 3 needs both.
+
+> **HTTP-specific recovery — no usable connection.** If platform-skill recovery yields nothing (empty after `--all-folders` + `--refresh`, user declines to create one), the HTTP node has unique fallback options. Ask the user to confirm the path — **manual mode is the recommended auto-fallback**, pre-selected, since it unblocks the node without a connection:
+>
+> - **Switch this node to manual mode** *(recommended)* — abandon this walkthrough and follow [impl-manual.md](impl-manual.md). Manual changes the auth model (you supply auth yourself), so this needs explicit confirmation.
+> - **Create a new connection now** — `uip is connections create "<target-connector-key>"` starts the OAuth flow. User completes browser auth themselves, then re-run `uip is connections list` to pick up the new connection.
+> - **Skip this node**.
+> - **Something else**.
+>
+> Auto-try the fallback, but do not finalize a mode switch without the user's confirmation; do not invent a placeholder ID; do not skip the node without explicit selection. See the dropdown question rule in [SKILL.md](../../../../SKILL.md).
+
+## Step 3 — Configure the node
+
+> **STOP — open the platform skill before configuring.** Before composing `url` / `query` / `body`, read [/uipath:uipath-platform — http-request.md](../../../../../uipath-platform/references/integration-service/http-request.md) and resolve every value you don't already have (IDs from names, required body fields, endpoint path, response shape).
+>
+> - **If the target connector is listed in that skill's `vendor-docs-registry.json`:** you MUST follow its **Step 0 (Ground Against the Vendor's API Docs)** — read the `docsUrl` + `notes` and confirm the exact endpoint with the `http-request` probe before running `node configure`. Pass the endpoint path verbatim: vendor method names can contain literal dots (Slack ``chat.postMessage`) — the dot is part of the path segment.
+> - **If the connector is NOT listed:** the registry-grounding step does not apply — resolve missing values via the `http-request` probe / vendor docs as usual.
+
+```bash
+uip maestro flow node configure <ProjectName>.flow <nodeId> \
+  --detail '{
+    "authentication": "connector",
+    "targetConnector": "<target-connector-key>",
+    "connectionId": "<target-connection-id>",
+    "folderKey": "<folder-key>",
+    "method": "GET",
+    "url": "/api/endpoint",
+    "query": {"param1": "value1"}
+  }' --output json
+```
+
+> **Connector mode supports `application/json` request and response bodies only.**
+
+The CLI:
+
+- Builds the full `inputs.detail` (connector, connectionId, bodyParameters, essentialConfiguration)
+- Auto-fills both `bodyParameters.path` and `bodyParameters.url` from the single `url` value you pass
+- Generates `bindings_v2.json`
+- Creates a connection resource file under `resources/solution_folder/connection/`
+
+**Dynamic values:** connector input fields do not resolve `{$vars.x}` brace-templates — use `=js:` expressions for any dynamic `url` / `headers` / `body` / `query`. Pass the `=js:` string verbatim in `--detail`. Full rationale and examples: [impl.md — Dynamic values](impl.md#dynamic-values-in-url--headers--body--query).
+
+## Step 4 — (Optional) Response branches
+
+Skip unless you need to route downstream paths based on response content (e.g., `items.length > 0` vs empty). For generic call-failure handling use the `error` port in Step 5 instead. Full syntax and rules: [impl.md — Conditional branches](impl.md#conditional-branches).
+
+## Step 5 — Wire edges
+
+The HTTP node's target port is `input`. Source ports: `default` (success), `error` (network/non-2xx), `branch-{id}` (one per Step 4 entry). Wire `default` to the next node. Wire `error` to a handler **only when the requirements say what a failed call should do** — with no `error` edge the call faults the flow, which is the correct default, and setting `inputs.errorHandlingEnabled: true` without the edge swallows the failure into a run that reports success. See [file-format.md — Default: off](../../../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles).
+
+Edge JSON shapes and all four examples (upstream→node, default→downstream, error→handler, branch→downstream): [impl.md — Wire edges](impl.md#wire-edges).
+
+## Debug
+
+See [impl.md — Debug](impl.md#debug). For connector mode, the most common errors are `not_authed` / 401/403 (expired connection — ping it) and `Connection not found` (wrong connector key or connection ID — re-list).

package/skills/uipath-maestro-flow/references/author/plugins/http/impl-manual.md

@@ -0,0 +1,68 @@
+# HTTP Request Node — Manual Mode
+
+Use this walkthrough when no IS connector exists, the API needs no auth (or auth passed in headers), or you are prototyping against an arbitrary REST endpoint. For connector-managed auth, use [impl-connector.md](impl-connector.md).
+
+**No connection lookup is required.** Manual mode uses `ImplicitConnection`; there are no IS bindings.
+
+Before starting, read [impl.md](impl.md) for the node type, registry validation, and the **always use `node configure`** rule. Follow Steps 1–4 in order.
+
+## Step 1 — Add the node
+
+Run:
+
+```bash
+uip maestro flow node add <ProjectName>.flow core.action.http.v2 \
+  --label "<HTTP node label>" --output json
+```
+
+> **Inside a loop body?** Add `--parent <LOOP_NODE_ID>` to set `parentId`. Without it, the node runs outside the loop context and outputs are null. See [loop/impl.md](../loop/impl.md).
+
+Save `<nodeId>` for Step 2. Leave `inputs` empty; Step 2 populates `inputs.detail`. Do not hand-author the definition. The CLI copies the manifest byte-for-byte from the registry into `definitions[]`, adds the node instance, registers `variables.nodes`, and inserts a `layout.nodes` placeholder. See [impl.md — Add the node](impl.md#add-the-node).
+
+## Step 2 — Configure the node
+
+Resolve missing values before composing `url`, `query`, or `body`, including IDs from names, required body fields, and the response shape. See [/uipath:uipath-platform — http-request.md](../../../../../uipath-platform/references/integration-service/http-request.md).
+
+Run:
+
+```bash
+uip maestro flow node configure <ProjectName>.flow <nodeId> \
+  --detail '{
+    "authentication": "manual",
+    "method": "GET",
+    "url": "https://api.example.com/endpoint",
+    "query": {"param1": "value1"}
+  }' --output json
+```
+
+The CLI builds `inputs.detail` with manual auth, `ImplicitConnection`, `bodyParameters`, and `essentialConfiguration`. It does **not** generate `bindings_v2.json` or a connection resource file; manual mode needs neither.
+
+Set `url` to a full URL (scheme + host + path). Pass controlled auth headers under `headers`; for example, run:
+
+```bash
+uip maestro flow node configure <ProjectName>.flow <nodeId> \
+  --detail '{
+    "authentication": "manual",
+    "method": "GET",
+    "url": "https://api.example.com/me",
+    "headers": {"Authorization": "=js:`Bearer ${$vars.apiToken}`"}
+  }' --output json
+```
+
+HTTP input fields do not resolve `{$vars.x}` brace-templates. Use `=js:` expressions for dynamic `url`, `headers`, `body`, or `query`, and pass each `=js:` string verbatim in `--detail`. See [impl.md — Dynamic values](impl.md#dynamic-values-in-url--headers--body--query).
+
+## Step 3 — (Optional) Response branches
+
+Skip this step unless downstream paths must be routed from response content, such as `items.length > 0` versus empty. Use the `error` port in Step 4 for generic call-failure handling. See [impl.md — Conditional branches](impl.md#conditional-branches).
+
+## Step 4 — Wire edges
+
+The HTTP node's target port is `input`. Source ports are `default` (success), `error` (network/non-2xx), and `branch-{id}` (one per Step 3 entry).
+
+Wire `default` to the next node. Wire `error` to a handler **only when the requirements specify what a failed call should do**. Without an `error` edge, the call faults the flow, which is the correct default. Do not set `inputs.errorHandlingEnabled: true` without an `error` edge: that swallows the failure into a run that reports success. See [file-format.md — Default: off](../../../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles).
+
+See [impl.md — Wire edges](impl.md#wire-edges) for edge JSON shapes and all four examples: upstream→node, default→downstream, error→handler, and branch→downstream.
+
+## Debug
+
+See [impl.md — Debug](impl.md#debug). In manual mode, watch for `ImplicitConnection` errors; they indicate a missing `authentication: "manual"` flag or a non-URL `url` value.

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

@@ -0,0 +1,173 @@
+# HTTP Request Node — Implementation
+
+Implement managed HTTP requests with `core.action.http.v2`: choose a mode, add the node with the CLI, configure it with `node configure`, wire its ports, and validate it.
+
+## Node type and mode
+
+Use `core.action.http.v2` for every HTTP request. `core.action.http` (v1) is deprecated.
+
+| Mode | Use when | Walkthrough |
+| --- | --- | --- |
+| **Connector** | The target system has an IS connector and authentication uses an existing IS connection (OAuth/API key). | [impl-connector.md](impl-connector.md) |
+| **Manual** | No connector exists, the API is public/no-auth, or quick prototyping is required. | [impl-manual.md](impl-manual.md) |
+
+Prefer a curated connector activity. If none exists, try connector mode. If it cannot be configured because the connector lacks HTTP request support (`HasHttpRequest` false) or no usable IS connection exists, fall through to manual mode automatically. Confirm the switch with the user before finalizing because manual mode changes authentication. See [impl-connector.md — Step 2](impl-connector.md#step-2--identify-target-connection).
+
+The `--detail` payload differs by mode only in `authentication` (`"connector"` or `"manual"`) and connector-only fields `targetConnector`, `connectionId`, and `folderKey`. Connector-mode `url` is relative to the connector base; manual-mode `url` is absolute. Node creation, dynamic values, branches, edges, and debugging are shared.
+
+<a id="critical-use-node-configure"></a>
+## Configure through the CLI
+
+Do not hand-write `inputs.detail`, `bindings_v2.json`, or connection resource files. Run `uip maestro flow node configure`; it builds the required configuration from `--detail`, including `essentialConfiguration`. `core.action.http.v2` is CLI-owned per [Author capability — Node ownership](../../CAPABILITY.md#node-ownership--who-authors-the-node), with the same envelope rules as connector activities.
+
+## Validate the registry
+
+Run:
+
+```bash
+uip maestro flow registry get core.action.http.v2 --output json
+```
+
+Confirm `Data.Node.handleConfiguration` has target port `input` and source ports `branch-{item.id}` (dynamic, `repeat: inputs.branches`) and `default`; `Data.Node.supportsErrorHandling: true`; and model `serviceType` is `Intsvc.UnifiedHttpRequest`. HTTP v2 uses the implicit `error` port pattern shared by action nodes (see [Action Node Structure](../../../shared/action-nodes.md)).
+
+<a id="add-the-node"></a>
+## Add and configure
+
+Run:
+
+```bash
+uip maestro flow node add <ProjectName>.flow core.action.http.v2 \
+  --label "<HTTP node label>" --output json
+```
+
+Save the returned node ID. The CLI copies the manifest into `definitions[]`, adds the node to `nodes[]`, registers `variables.nodes`, inserts a `layout.nodes` placeholder byte-for-byte from the registry, and obtains `typeVersion` from the manifest's `version`; do not hardcode it.
+
+The CLI initializes:
+
+```json
+"inputs": {
+  "branches": [],
+  "timeout": "PT15M",
+  "retryCount": 0,
+  "swaggerDefinition": null,
+  "detail": {}
+}
+```
+
+Set `branches`, `timeout`, and `retryCount` during `node add` with `--input`; populate `inputs.detail` only with `node configure --detail`:
+
+```bash
+uip maestro flow node add <ProjectName>.flow core.action.http.v2 \
+  --label "<HTTP node label>" \
+  --input '{
+    "timeout": "PT30M",
+    "retryCount": 3,
+    "branches": [
+      { "id": "hasItems", "name": "Has Items", "conditionExpression": "$self.output.body.items.length > 0" },
+      { "id": "empty",    "name": "Empty",    "conditionExpression": "$self.output.body.items.length == 0" }
+    ]
+  }' --output json
+```
+
+`timeout` is an ISO 8601 duration such as `PT15M`, `PT1H`, or `P1D` and defaults to `PT15M`. `retryCount` is an integer and defaults to `0`. `branches` is optional and belongs at `inputs.branches`, not `inputs.detail.branches`. Do not edit `inputs.*` afterward or hand-author the definition; run `uip maestro flow node add` and `uip maestro flow node configure`.
+
+<a id="dynamic-values-in-url--headers--body--query"></a>
+## Dynamic values
+
+Do not use `{$vars.x}` brace templates in IS activity inputs. Runtime `{...}` interpolation applies to native flow fields, not `inputs.detail.bodyParameters` on HTTP v2 or `uipath.connector.*` activities; such templates can be sent literally and cause a 400 response.
+
+Use `=js:` expressions for dynamic URL, header, body, and query values. `$vars` is available in the JavaScript context:
+
+```json
+"bodyParameters": {
+  "url": "=js:`https://api.example.com/users/${$vars.userId}/orders`",
+  "headers": {
+    "Authorization": "=js:'Bearer ' + $vars.apiToken",
+    "X-Request-ID": "=js:$metadata.instanceId"
+  },
+  "query": {
+    "since": "=js:$vars.startDate"
+  }
+}
+```
+
+Pass the expression string verbatim to `node configure`:
+
+```bash
+uip maestro flow node configure <Project>.flow <nodeId> \
+  --detail '{
+    "authentication": "manual",
+    "method": "GET",
+    "url": "=js:`https://api.example.com/users/${$vars.userId}`"
+  }' --output json
+```
+
+## Conditional branches
+
+Use branches only to route based on response content, not to handle call failures; failures use the `error` port. Each `inputs.branches` entry creates `branch-{id}`; `$self` refers to the HTTP node output. Set branches with `node add --input`; `node configure --detail` does not accept them. Do not prefix `conditionExpression` with `=js:`; branch conditions are automatically evaluated as JS.
+
+## Wire edges
+
+The target port is `input`. Source ports are `default` (primary success output or fallback when no configured branch matches), `error` (network, timeout, or non-2xx failure not caught by a branch), and `branch-{id}` (one per `inputs.branches` entry).
+
+Use `Edit` to add edge objects to `edges[]`; do not use `uip maestro flow edge add` for structural wiring. Use exact port names and this shape:
+
+```json
+{
+  "id": "e-<upstreamNodeId>-<nodeId>",
+  "sourceNodeId": "<upstreamNodeId>",
+  "sourcePort": "<port>",
+  "targetNodeId": "<nodeId>",
+  "targetPort": "input"
+}
+```
+
+For success and error handling:
+
+```json
+{
+  "id": "e-<nodeId>-<downstreamNodeId>",
+  "sourceNodeId": "<nodeId>",
+  "sourcePort": "default",
+  "targetNodeId": "<downstreamNodeId>",
+  "targetPort": "input"
+}
+```
+
+```json
+{
+  "id": "e-<nodeId>-<errorHandlerId>",
+  "sourceNodeId": "<nodeId>",
+  "sourcePort": "error",
+  "targetNodeId": "<errorHandlerId>",
+  "targetPort": "input"
+}
+```
+
+Add an `error` edge only when requirements specify failure behavior. Without one, a failed call faults the flow. When an HTTP node has an outgoing `error` edge, set `inputs.errorHandlingEnabled: true`. `uip maestro flow edge add --source-port error` and `uip maestro flow format` set it automatically; direct JSON edits must set it explicitly. Never set it without an error edge: that suppresses the fault and can report a failed call as successful. See [file-format.md — Default: off](../../../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles).
+
+For a branch edge, use:
+
+```json
+{
+  "id": "e-<nodeId>-<hasItemsDownstream>",
+  "sourceNodeId": "<nodeId>",
+  "sourcePort": "branch-hasItems",
+  "targetNodeId": "<hasItemsDownstream>",
+  "targetPort": "input"
+}
+```
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `not_authed` or 401/403 | v1 node, missing bindings, or expired connection | Verify `core.action.http.v2`, check `bindings_v2.json`, and ping the connection. |
+| `configuration` field missing | Node was not configured through the CLI | Run `uip maestro flow node configure`; do not hand-write `inputs.detail`. |
+| `flow validate` reports missing `uiPathActivityTypeId` on `core.action.http.v2` | Definition was hand-authored | Remove the node, run `uip maestro flow node add <file> core.action.http.v2 ...`, then run `node configure`. |
+| Connection not found | Wrong connection ID or connector key | Re-run `uip is connections list` for the target connector. |
+| Wrong API response | Incorrect `url` or `query` | Check the target service API documentation. |
+| `ImplicitConnection` errors | Manual mode is misconfigured | Verify `authentication: "manual"` and a full URL. |
+| Flow faults on 4xx/5xx | No `error` edge | This is expected when no fallback is required. Otherwise add `sourcePort: "error"` to an error-handler node. See [Implicit error port on action nodes](../../../shared/file-format.md#implicit-error-port-on-action-nodes). |
+| Flow reports `Completed` although the API call failed | `inputs.errorHandlingEnabled: true` without a handler, or an error edge enters the happy path/success End node | Remove the flag without an error edge; otherwise route the error to a distinct End node with an error/status output or `core.logic.terminate`. See [Do not swallow the failure](../../../shared/file-format.md#do-not-swallow-the-failure). |
+| Edge `source-port output` rejected | Variable namespace used as a port | Use `default`, `error`, or `branch-{id}`. `output` is only the variable namespace `$vars.{nodeId}.output`. |

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

@@ -0,0 +1,107 @@
+# HTTP Request Node — Planning
+
+> **MUST READ FIRST — confirm Managed HTTP Request fits your use case before authoring:** [/uipath:uipath-platform — http-request.md](../../../../../uipath-platform/references/integration-service/http-request.md). This planning doc is the flow-specific layer on top of it.
+
+## Node Type
+
+`core.action.http.v2` (Managed HTTP Request)
+
+> **Always use `core.action.http.v2`** for all HTTP requests — both connector-authenticated and manual. The older `core.action.http` (v1) is deprecated and does not pass IS credentials at runtime.
+
+## When to Use a Managed HTTP Request Node
+
+| Situation | Use Managed HTTP? |
+| --- | --- |
+| Connector exists but lacks the specific curated activity, and does **not** report `V4Compatible` | Yes — connector mode ([impl-connector.md](impl-connector.md)), **if the connector supports HTTP request activity** (verify `HasHttpRequest` — see [Prerequisites](#prerequisites)) |
+| Connector exists but lacks the specific curated activity, and **does** report `V4Compatible` | No — generate a non-catalog activity instead ([connector/planning.md](../connector/planning.md#decision-order)) |
+| No connector exists, but service has a REST API | Yes — manual mode ([impl-manual.md](impl-manual.md)) |
+| Quick prototyping against any REST API | Yes — manual mode ([impl-manual.md](impl-manual.md)) |
+| Connector exists and covers the use case | No — use [Connector Activity](../connector/planning.md) |
+| Target system has no API (desktop app) | No — use [RPA Workflow](../rpa/planning.md) |
+
+Both flags come from the same call: `uip is connectors metadata <key> --output json`
+→ `Data[0].Flags.V4Compatible` and `Data[0].HasHttpRequest`.
+
+For the two-mode concept (connector vs. manual) and the `url` / auth rules per mode, see the platform doc linked at the top.
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `default`, `error`, `branch-{id}` (dynamic, one per `inputs.branches` entry) |
+
+- `default` — primary success output, or fallback when configured branches don't match.
+- `error` — implicit error port; fires when the call fails (network error, timeout, non-2xx not caught by a branch). Shared with all action nodes — see [Implicit error port on action nodes](../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+- `branch-{id}` — HTTP-specific, configured via `inputs.branches` (response-content routing). See [Conditional Branches](#conditional-branches) below.
+
+## Output Variables
+
+- `$vars.{nodeId}.output` — `{ body, code, method, rawStringBody, request }` on success
+- `$vars.{nodeId}.error` — `{ code, message, detail, category, status }` when the error port fires
+
+## Conditional Branches
+
+Use `inputs.branches` when you need to route downstream paths based on response content (e.g., empty vs non-empty results). For generic call-failure handling, prefer the shared `error` port instead — don't enumerate every bad status code as a branch.
+
+Each branch's `conditionExpression` is a JS expression with `$self` bound to the current HTTP node's output:
+
+```json
+{
+  "inputs": {
+    "branches": [
+      { "id": "hasItems",  "name": "Has Items",  "conditionExpression": "$self.output.body.items.length > 0" },
+      { "id": "empty",     "name": "Empty",      "conditionExpression": "$self.output.body.items.length == 0" }
+    ]
+  }
+}
+```
+
+Wire `branch-hasItems` / `branch-empty` as source ports on outgoing edges. `default` fires when no branch condition matches.
+
+> **Do not use `=js:` on `conditionExpression`** — HTTP branch conditions are evaluated as JS automatically (same rule as decision/switch expressions). See [variables-and-expressions.md](../../../shared/variables-and-expressions.md#http-branch-condition-inputsbranchesconditionexpression).
+
+## Dynamic values
+
+IS activity input fields (`url`, `headers`, `body`, `query` under `bodyParameters`) do **not** resolve `{$vars.x}` brace-templates — the template runner only applies to native flow fields. Use `=js:` expressions for any dynamic value; template literals with `${...}` interpolation or string concatenation both work. See [Dynamic values](impl.md#dynamic-values-in-url--headers--body--query) for the full rationale and examples.
+
+## Key Inputs (`--detail` for `node configure`)
+
+Run `uip maestro flow node configure` with a `--detail` JSON. The CLI builds the full `inputs.detail` payload, `bindings_v2.json`, and connection resource files automatically. **Do not hand-write `inputs.detail`.**
+
+**Connector mode** (IS connection auth):
+
+| `--detail` Key | Required | Description |
+| --- | --- | --- |
+| `authentication` | Yes | `"connector"` |
+| `method` | Yes | HTTP method: GET, POST, PUT, PATCH, DELETE |
+| `targetConnector` | Yes | Target connector key (e.g., `"uipath-salesforce-slack"`) |
+| `connectionId` | Yes | Target connector's IS connection ID (from `uip is connections list --all-folders`) |
+| `folderKey` | Yes | Orchestrator folder key (from `uip is connections list --all-folders`) |
+| `url` | No | API endpoint URL/path (e.g., `"/conversations.replies"`). Auto-fills both `bodyParameters.path` and `bodyParameters.url`. |
+| `query` | No | Query parameters as key-value object |
+| `headers` | No | Additional headers as key-value object |
+| `body` | No | Request body (for POST/PUT/PATCH). Connector mode is **`application/json` only** (request and response) — no other content type. |
+
+**Manual mode** (no connector auth):
+
+| `--detail` Key | Required | Description |
+| --- | --- | --- |
+| `authentication` | Yes | `"manual"` |
+| `method` | Yes | HTTP method: GET, POST, PUT, PATCH, DELETE |
+| `url` | Yes | Full target URL |
+| `query` | No | Query parameters as key-value object |
+| `headers` | No | Additional headers as key-value object |
+| `body` | No | Request body (for POST/PUT/PATCH) |
+
+## Prerequisites
+
+- `uip login` required (for both modes — node type comes from registry)
+- For connector mode: connector must support the HTTP request activity — verify the `HasHttpRequest` flag via `uip is connectors get "<connector-key>"`. If false, fall back to manual mode — confirm the switch with the user before finalizing. See [impl-connector.md Step 2](impl-connector.md#step-2--identify-target-connection).
+- For connector mode: a healthy IS connection must exist for the **target connector**. If none exists, auto-fall-through to manual mode is the recommended fallback — but confirm the mode switch with the user before finalizing. See [impl-connector.md Step 2 — HTTP-specific recovery](impl-connector.md#step-2--identify-target-connection) for the user-confirmation flow (switch-to-manual / create-now / skip).
+- `uip maestro flow registry pull` to cache the `core.action.http.v2` definition
+
+## Planning Annotation
+
+In the architectural plan, annotate managed HTTP nodes as:
+- Connector mode: `managed-http: <service> — <operation>` (e.g., "managed-http: Slack — GET /conversations.replies")
+- Manual mode: `managed-http: manual — <method> <url>` (e.g., "managed-http: manual — GET https://api.example.com/data")