@uipath/skills 1.195.0

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

@@ -0,0 +1,242 @@
+# Loop Node — Implementation
+
+## Node Type
+
+`core.logic.loop`
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.logic.loop --output json
+```
+
+Confirm: input ports `input` and `loopBack`, output ports `success` and `output`, required input `collection`. Set the node instance `typeVersion` to the `version` field from this response — do not hardcode it.
+
+## JSON Structure
+
+### Loop node
+
+```json
+{
+  "id": "loop1",
+  "type": "core.logic.loop",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Loop over items" },
+  "inputs": {
+    "collection": "=js:$vars.fetchData.output.body.items",
+    "parallel": false
+  }
+}
+```
+
+Set `"parallel": true` to execute all iterations concurrently.
+
+### Loop body nodes — `parentId` required
+
+Every node inside the loop body **must** have `"parentId"` set to the loop node's ID. Without this, the runtime does not know the node is part of the loop and variableUpdates will not fire per-iteration.
+
+```json
+{
+  "id": "processItem",
+  "type": "core.action.script",
+  "typeVersion": "1.0",
+  "display": { "label": "Process item" },
+  "inputs": {
+    "script": "return $vars.product * $vars.loop1.currentItem"
+  },
+  "parentId": "loop1"
+}
+```
+
+> **Critical:** If you omit `parentId`, the node executes outside the loop context. State variables will not update across iterations and loop outputs like `currentItem` will be inaccessible.
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for the node-specific `inputs` and `parentId`.
+
+## Wiring
+
+Loop nodes have a specific wiring pattern:
+
+- `input` — entry from upstream
+- `output` — into the loop body (first body node)
+- `loopBack` — return from last body node back to loop
+- `success` — exit after loop completes (to next downstream node)
+
+See [editing-operations.md](../../editing-operations.md) for edge add procedures.
+
+## Accessing Loop Variables Inside Body
+
+Inside the loop body, access the current item via `$vars.<loopId>.currentItem`:
+
+```javascript
+// In a Script node inside the loop body (parentId must be set to the loop node)
+const item = $vars.loop1.currentItem;
+const index = $vars.loop1.currentIndex;
+return { processed: item.name.toUpperCase(), position: index };
+```
+
+| Variable | Description |
+| --- | --- |
+| `$vars.<loopId>.currentItem` | The item being processed in this iteration |
+| `$vars.<loopId>.currentIndex` | 0-based iteration index |
+| `$vars.<loopId>.collection` | The full collection being iterated |
+
+> **Do not use `iterator.currentItem`.** The correct access pattern is `$vars.<loopId>.currentItem` where `<loopId>` is the loop node's `id` (e.g., `$vars.loop1.currentItem`).
+
+### Required node variables for loop outputs
+
+For `$vars.<loopId>.currentItem` etc. to resolve, you must add corresponding entries to `variables.nodes`:
+
+```json
+{
+  "variables": {
+    "nodes": [
+      {
+        "id": "loop1.currentItem",
+        "type": "any",
+        "description": "The current item being iterated in the loop",
+        "binding": { "nodeId": "loop1", "outputId": "currentItem" }
+      },
+      {
+        "id": "loop1.currentIndex",
+        "type": "number",
+        "description": "The current iteration index (0-based)",
+        "binding": { "nodeId": "loop1", "outputId": "currentIndex" }
+      },
+      {
+        "id": "loop1.collection",
+        "type": "array",
+        "description": "The collection being iterated over",
+        "binding": { "nodeId": "loop1", "outputId": "collection" }
+      },
+      {
+        "id": "loop1.output",
+        "type": "array",
+        "description": "Aggregated results from all loop iterations",
+        "binding": { "nodeId": "loop1", "outputId": "output" }
+      }
+    ]
+  }
+}
+```
+
+## State Accumulation with variableUpdates
+
+To accumulate state across loop iterations (counters, running totals), use an `inout` variable with a `variableUpdate` on the body node:
+
+```json
+{
+  "variables": {
+    "globals": [
+      {
+        "id": "runningTotal",
+        "direction": "inout",
+        "type": "number",
+        "defaultValue": 0
+      }
+    ],
+    "variableUpdates": {
+      "bodyNode": [
+        {
+          "variableId": "runningTotal",
+          "expression": "=js:$vars.bodyNode.output"
+        }
+      ]
+    }
+  }
+}
+```
+
+The variableUpdate fires after each iteration, so the `inout` variable carries the accumulated value into the next iteration.
+
+> **Critical:** The variableUpdate expression **cannot** access loop iteration variables like `$vars.<loopId>.currentItem`. These are only available inside the body node's script. The variableUpdate must reference the body node's output (e.g., `=js:$vars.bodyNode.output`). If you need to compute using `currentItem`, do the computation in the script and reference the script's output in the variableUpdate.
+
+## Complete Example — Loop with State Accumulation
+
+A flow that iterates over a collection, accumulates a result in an `inout` variable via a Script body node, and outputs the final value.
+
+```json
+{
+  "nodes": [
+    {
+      "id": "start",
+      "type": "core.trigger.manual",
+      "typeVersion": "1.0",
+      "display": { "label": "Manual trigger" },
+      "inputs": { "entryPointId": "..." }
+    },
+    {
+      "id": "loop1",
+      "type": "core.logic.loop",
+      "typeVersion": "1.0",
+      "display": { "label": "Loop" },
+      "inputs": { "collection": "=js:$vars.inputItems", "parallel": false }
+    },
+    {
+      "id": "bodyScript",
+      "type": "core.action.script",
+      "typeVersion": "1.0",
+      "display": { "label": "Process item" },
+      "inputs": {
+        "script": "return $vars.accumulator + $vars.loop1.currentItem;"
+      },
+      "parentId": "loop1"
+    },
+    {
+      "id": "end1",
+      "type": "core.control.end",
+      "typeVersion": "1.0",
+      "display": { "label": "End" },
+      "inputs": {},
+      "outputs": {
+        "result": { "source": "=js:$vars.accumulator" }
+      }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "sourceNodeId": "start", "sourcePort": "output", "targetNodeId": "loop1", "targetPort": "input" },
+    { "id": "e2", "sourceNodeId": "loop1", "sourcePort": "output", "targetNodeId": "bodyScript", "targetPort": "input" },
+    { "id": "e3", "sourceNodeId": "bodyScript", "sourcePort": "success", "targetNodeId": "loop1", "targetPort": "loopBack" },
+    { "id": "e4", "sourceNodeId": "loop1", "sourcePort": "success", "targetNodeId": "end1", "targetPort": "input" }
+  ],
+  "variables": {
+    "globals": [
+      { "id": "inputItems", "direction": "in", "type": "array", "defaultValue": [] },
+      { "id": "accumulator", "direction": "inout", "type": "number", "defaultValue": 0 },
+      { "id": "result", "direction": "out", "type": "number" }
+    ],
+    "nodes": [
+      { "id": "loop1.currentItem", "type": "any", "binding": { "nodeId": "loop1", "outputId": "currentItem" } },
+      { "id": "loop1.currentIndex", "type": "number", "binding": { "nodeId": "loop1", "outputId": "currentIndex" } },
+      { "id": "loop1.collection", "type": "array", "binding": { "nodeId": "loop1", "outputId": "collection" } },
+      { "id": "loop1.output", "type": "array", "binding": { "nodeId": "loop1", "outputId": "output" } },
+      { "id": "bodyScript.output", "type": "object", "binding": { "nodeId": "bodyScript", "outputId": "output" } },
+      { "id": "bodyScript.error", "type": "object", "binding": { "nodeId": "bodyScript", "outputId": "error" } }
+    ],
+    "variableUpdates": {
+      "bodyScript": [
+        { "variableId": "accumulator", "expression": "=js:$vars.bodyScript.output" }
+      ]
+    }
+  }
+}
+```
+
+Key points in this pattern:
+- `bodyScript` has `"parentId": "loop1"` — places it inside the loop
+- Script accesses `$vars.loop1.currentItem` for the current iteration value
+- `variableUpdate` on `bodyScript` writes the script's return value back to `accumulator`
+- `accumulator` is `inout` so it persists across iterations
+- End node maps the final accumulated value to the `out` variable
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Collection is empty or null | Expression evaluates to null/undefined | Check `collection` expression and upstream output |
+| `$vars.loop1.currentItem` is undefined | Missing node variable binding or missing `parentId` | Add `loop1.currentItem` to `variables.nodes` and set `parentId` on body nodes |
+| State variable not updating across iterations | Body node missing `parentId` | Add `"parentId": "<loopId>"` to every node inside the loop body |
+| State variable becomes `NaN` | variableUpdate expression uses `$vars.<loopId>.currentItem` | Loop variables are not available in variableUpdate expressions. Do the computation in the script and reference `$vars.<bodyNodeId>.output` in the variableUpdate |
+| Infinite loop | Edges wired incorrectly | Ensure only `loopBack` creates the cycle, not arbitrary edges |
+| No output after loop | Missing `success` edge | Wire the `success` port to the next downstream node |

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

@@ -0,0 +1,52 @@
+# Loop Node — Planning
+
+## Node Type
+
+`core.logic.loop`
+
+## When to Use
+
+Use a Loop node to iterate over a collection of items. Supports sequential and parallel execution.
+
+### Selection Heuristics
+
+| Situation | Use Loop? |
+| --- | --- |
+| Process each item in an array | Yes |
+| Run the same operation on multiple inputs concurrently | Yes (with `parallel: true`) |
+| Simple data transformation on a collection | No — use [Transform](../transform/planning.md) |
+| Distribute work items to robots | No — use [Queue](../queue/planning.md) |
+
+## Ports
+
+| Input Port(s) | Output Port(s) |
+| --- | --- |
+| `input`, `loopBack` | `success`, `output`, `error` |
+
+- `loopBack` — receives the edge returning from the last node inside the loop body
+- `success` — fires after all iterations complete
+- `output` — carries aggregated results from all iterations
+- `error` — implicit error port shared with all action nodes; fires when the loop or an iteration throws. See [Implicit error port on action nodes](../../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `collection` | Yes | Expression pointing to an array (e.g., `$vars.fetchData.output.body.items`) |
+| `parallel` | No | `true` to execute all iterations concurrently (default: sequential) |
+
+## Loop Variables (available inside loop body only)
+
+- `$vars.<loopId>.currentItem` — the item being processed in this iteration
+- `$vars.<loopId>.currentIndex` — 0-based iteration index
+- `$vars.<loopId>.collection` — the full collection
+
+Where `<loopId>` is the loop node's `id` (e.g., `$vars.loop1.currentItem`).
+
+## Wiring Rules
+
+- The loop body starts from the `output` port of the loop node
+- The last node in the loop body connects back to the loop's `loopBack` port
+- After all iterations, execution continues from the `success` port
+- Do not create cycles except through the `loopBack` mechanism
+- **Every node inside the loop body must have `"parentId": "<loopId>"`** — without this, variableUpdates will not fire per-iteration and loop variables will be inaccessible

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

@@ -0,0 +1,43 @@
+# Merge Node — Implementation
+
+## Node Type
+
+`core.logic.merge`
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.logic.merge --output json
+```
+
+Confirm: input port `input` (accepts multiple connections), output port `output`. Set the node instance `typeVersion` to the `version` field from this response — do not hardcode it.
+
+## JSON Structure
+
+```json
+{
+  "id": "joinBranches",
+  "type": "core.logic.merge",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Join Branches" },
+  "inputs": {}
+}
+```
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for the node-specific `inputs`.
+
+## Wiring
+
+- `input` — accepts multiple incoming edges (one per parallel branch). All branches must reach the merge before it continues.
+- `output` — single outgoing edge to the next downstream node.
+
+See [editing-operations.md](../../editing-operations.md) for edge add procedures.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Merge never completes | One parallel branch has no path to the merge node | Ensure all forked branches reach the merge |
+| Unexpected execution order | Branches assumed to complete in order | Merge waits for all — don't depend on arrival order |

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

@@ -0,0 +1,29 @@
+# Merge Node — Planning
+
+## Node Type
+
+`core.logic.merge`
+
+## When to Use
+
+Use a Merge node to synchronize parallel branches before continuing. It waits for all incoming paths to complete.
+
+### Selection Heuristics
+
+| Situation | Use Merge? |
+| --- | --- |
+| Two or more parallel branches need to join before continuing | Yes |
+| Sequential pipeline (no parallel branches) | No — wire nodes directly |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` (accepts multiple connections) | `output` |
+
+## Wiring Rules
+
+- Connect each parallel branch's terminal node to the Merge node's `input` port
+- Merge accepts multiple incoming edges on the same `input` port
+- Execution continues from `output` only after all incoming paths complete
+- Use after forking from a single node to multiple downstream nodes

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

@@ -0,0 +1,94 @@
+# Queue Node — Implementation
+
+## Node Types
+
+| Node Type | Description |
+| --- | --- |
+| `core.action.queue.create` | Fire-and-forget queue item creation |
+| `core.action.queue.create-and-wait` | Create queue item and wait for result |
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.action.queue.create --output json
+uip maestro flow registry get core.action.queue.create-and-wait --output json
+```
+
+Confirm: input port `input`, output port `success`. Set each node instance's `typeVersion` to the `version` field from the matching response — do not hardcode it.
+
+## JSON Structure
+
+```json
+{
+  "id": "enqueueItem",
+  "type": "core.action.queue.create",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Enqueue Invoice" },
+  "inputs": {
+    "queue": "InvoiceProcessingQueue",
+    "itemData": "=js:JSON.stringify({ orderId: $vars.order.id, amount: $vars.order.total })",
+    "priority": "High",
+    "reference": "=js:$vars.order.id",
+    "deferDate": "2026-04-01T10:00:00Z",
+    "dueDate": "2026-04-07T17:00:00Z"
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the queue operation",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the queue operation fails",
+      "source": "=result.Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for the node-specific `inputs`.
+
+## Wait Variant
+
+`core.action.queue.create-and-wait` blocks execution until the queue item is processed by a robot. The processed result is available via `$vars.{nodeId}.output`.
+
+```json
+{
+  "id": "processAndWait",
+  "type": "core.action.queue.create-and-wait",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Process and Wait" },
+  "inputs": {
+    "queue": "InvoiceProcessingQueue",
+    "itemData": "=js:JSON.stringify({ invoiceId: $vars.invoiceId })"
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the queue operation",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the queue operation fails",
+      "source": "=result.Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Queue not found | Queue name doesn't match Orchestrator | Verify queue name in Orchestrator |
+| `itemData` invalid | Not valid JSON | Ensure `JSON.stringify()` wraps the data object |
+| Queue item stuck | No robot available to process | Check Orchestrator robot allocation |
+| Wait timeout | Robot took too long to process item | Check queue processing time and robot availability |

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

@@ -0,0 +1,44 @@
+# Queue Node — Planning
+
+## Node Types
+
+| Node Type | Description |
+| --- | --- |
+| `core.action.queue.create` | Create a queue item and continue immediately (fire-and-forget) |
+| `core.action.queue.create-and-wait` | Create a queue item and wait for processing to complete |
+
+## When to Use
+
+Use Queue nodes to distribute work items to robots via Orchestrator queues.
+
+### Selection Heuristics
+
+| Situation | Use Queue? |
+| --- | --- |
+| Distribute work to robots — fire-and-forget | Yes (`create`) |
+| Distribute work and need the result before continuing | Yes (`create-and-wait`) |
+| Direct process invocation with known inputs | No — use [RPA Workflow](../rpa/planning.md) |
+| Iterate over items sequentially in the flow | No — use [Loop](../loop/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `success` |
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `queue` | Yes | Orchestrator queue name |
+| `itemData` | No | JSON payload for the queue item |
+| `priority` | No | `Low`, `Normal` (default), `High` |
+| `reference` | No | Tracking reference string |
+| `deferDate` | No | ISO 8601 — earliest time to process |
+| `dueDate` | No | ISO 8601 — deadline for processing |
+
+## Common Pattern — Fan-Out to Queue
+
+```text
+Manual Trigger -> Script (split batch) -> Loop -> Queue Create (per item) -> End Loop -> End
+```

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

@@ -0,0 +1,120 @@
+# RPA Node — Implementation
+
+RPA nodes invoke RPA processes. Pattern: `uipath.core.rpa-workflow.{key}`.
+
+## Discovery
+
+**Published (tenant registry):**
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.rpa-workflow" --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 RPA projects in the same `.uipx` solution.
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get "uipath.core.rpa-workflow.{key}" --output json
+uip maestro flow registry get "uipath.core.rpa-workflow.{key}" --local --output json
+```
+
+Confirm:
+
+- Input port: `input`
+- Output port: `output`
+- `model.serviceType` — `Orchestrator.StartJob`
+- `model.bindings.resourceSubType` — `Process`
+- `model.bindings.resourceKey` — the `<FolderPath>.<ResourceName>` string used to scope binding resolution
+- `inputDefinition` — may contain typed input fields (check `properties`)
+- `outputDefinition.output` — process return value
+- `outputDefinition.error` — error schema
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure below for the node-specific `inputs`.
+
+## JSON Structure
+
+### Node instance (inside `nodes[]`)
+
+The instance carries only per-instance data (`inputs`, `outputs`, `display`). BPMN type, serviceType, version, and binding/context templates come from the definition in `definitions[]`.
+
+```json
+{
+  "id": "processInvoices",
+  "type": "uipath.core.rpa-workflow.invoice-process-abc123",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Process Invoices" },
+  "inputs": {
+    "documentPath": "=js:$vars.fileLocation",
+    "batchSize": 50
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the RPA process",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the RPA process fails",
+      "source": "=result.Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+### Top-level `bindings[]` entries (sibling of `nodes`/`edges`/`definitions`)
+
+Add one entry per `(resourceKey, propertyAttribute)` pair. Share entries across node instances that reference the same RPA process — do NOT create duplicates.
+
+```json
+"bindings": [
+  {
+    "id": "bProcessInvoicesName",
+    "name": "name",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Finance/Automation.Invoice Processor",
+    "default": "Invoice Processor",
+    "propertyAttribute": "name",
+    "resourceSubType": "Process"
+  },
+  {
+    "id": "bProcessInvoicesFolderPath",
+    "name": "folderPath",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Finance/Automation.Invoice Processor",
+    "default": "Finance/Automation",
+    "propertyAttribute": "folderPath",
+    "resourceSubType": "Process"
+  }
+]
+```
+
+> For the resolution mechanics and why these entries are required, see [file-format.md — Bindings](../../../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings).
+
+## If the RPA Process Does Not Exist Yet
+
+Tell the user to create the RPA project inside the same solution using `uipath-rpa`. Once the project exists as a sibling in the `.uipx` solution, discover it with `uip maestro flow registry list --local --output json` and wire it directly — no publish required.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node type not found in registry | Process not published or registry stale | If in same solution: run `registry list --local`. Otherwise: run `uip login` then `uip maestro flow registry pull --force` |
+| Input schema mismatch | Inputs don't match `inputDefinition` | Run `registry get` and check required inputs in `inputDefinition.properties` |
+| Process execution failed | Underlying RPA process errored | Check `$vars.{nodeId}.error` for details |
+| Mock placeholder still in flow | Process not yet replaced | Follow the mock replacement workflow above |