@uipath/skills 1.195.0

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

@@ -0,0 +1,274 @@
+# Transform Node — Implementation
+
+## Node Types
+
+- `core.action.transform` — generic (chains multiple operations)
+- `core.action.transform.filter` — filter only
+- `core.action.transform.map` — map only
+- `core.action.transform.group-by` — group-by only
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.action.transform --output json
+uip maestro flow registry get core.action.transform.filter --output json
+uip maestro flow registry get core.action.transform.map --output json
+uip maestro flow registry get core.action.transform.group-by --output json
+```
+
+Confirm: input port `input`, output ports `output` and `error`, required inputs `collection` and `operations`. Set each node instance's `typeVersion` to the `version` field from the matching response — do not hardcode it.
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structures below for the node-specific `inputs` and `model` fields.
+
+## Collection Input Contract
+
+`inputs.collection` is a transform-specific path field, not a general `=js:` value field. Set it to the variable path that contains the array:
+
+```json
+"collection": "$vars.orders.output.items"
+```
+
+**NEVER** wrap transform `collection` in `=js:`. **NEVER** set it to an inline array literal. Both forms below are wrong:
+
+```json
+"collection": "=js:$vars.orders.output.items"
+```
+
+```json
+"collection": "=js:[{\"title\":\"Example\"}]"
+```
+
+The transform runtime turns the path string into a lookup such as `vars.orders.output.items`. If the string starts with `=js:` or contains an inline JSON/JS literal, that lookup resolves to an empty collection.
+
+For static data, store the array in a workflow variable `defaultValue` or emit it from an upstream static-data/script node, then point `collection` at that variable or node output. Filtering, mapping, and grouping still belong in transform nodes.
+
+---
+
+## Generic Transform (`core.action.transform`)
+
+Chains multiple operations (filter -> map -> groupBy) in a single node. Operations execute in order; each feeds into the next.
+
+```json
+{
+  "id": "transformChain",
+  "type": "core.action.transform",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Process Employees" },
+  "inputs": {
+    "collection": "$vars.fetchData.output.body.employees",
+    "operations": [
+      {
+        "id": "op1",
+        "type": "filter",
+        "config": {
+          "operation": "and",
+          "filters": [
+            { "id": "f1", "field": "active", "condition": "equals", "value": true }
+          ]
+        }
+      },
+      {
+        "id": "op2",
+        "type": "map",
+        "config": {
+          "keepOriginalFields": false,
+          "mappings": [
+            { "id": "m1", "field": "name", "transformation": "uppercase", "renameTo": "fullName" },
+            { "id": "m2", "field": "salary", "transformation": "copy", "renameTo": "" }
+          ]
+        }
+      }
+    ]
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the transform",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the transform fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+---
+
+## Filter (`core.action.transform.filter`)
+
+```json
+{
+  "id": "filterActive",
+  "type": "core.action.transform.filter",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Filter Active Orders" },
+  "inputs": {
+    "collection": "$vars.orders.output.items",
+    "operations": [
+      {
+        "id": "op1",
+        "type": "filter",
+        "config": {
+          "operation": "and",
+          "filters": [
+            { "id": "f1", "field": "status", "condition": "equals", "value": "active" },
+            { "id": "f2", "field": "amount", "condition": "greater_equal", "value": 100 }
+          ]
+        }
+      }
+    ]
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the transform",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the transform fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+**Filter conditions:** `equals`, `not_equals`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `contains`, `starts_with`, `ends_with`, `is_null`, `is_not_null`
+
+**Filter operations:** `and` (all conditions must match), `or` (any condition matches)
+
+> **Filter `value` is literal-only — no `$vars`, no `=js:`, no brace-templates.** The Transform runtime reads `value` as-is and does not evaluate expressions. Setting `"value": "$vars.threshold"`, `"value": "=js:$vars.threshold"`, or `"value": "{$vars.threshold}"` silently produces an empty filtered array — the filter is comparing each item's field against the literal string `$vars.threshold` (or `=js:...`), never against the intended number. Only literal scalars work: `"value": 500`, `"value": "active"`, `"value": true`. If you need a dynamic threshold, compute the filter inside a [Script](../script/impl.md) node instead, or hoist the literal into the flow design and keep the Transform filter for demo-time thresholds.
+
+**`field` accepts dot-paths** for nested object fields (e.g., `"field": "order.amount"`). Applies to `collection` elements.
+
+---
+
+## Map (`core.action.transform.map`)
+
+```json
+{
+  "id": "mapFields",
+  "type": "core.action.transform.map",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Normalize Names" },
+  "inputs": {
+    "collection": "$vars.rawData.output.items",
+    "operations": [
+      {
+        "id": "op1",
+        "type": "map",
+        "config": {
+          "keepOriginalFields": false,
+          "mappings": [
+            { "id": "m1", "field": "firstName", "transformation": "uppercase", "renameTo": "name" },
+            { "id": "m2", "field": "email", "transformation": "lowercase", "renameTo": "" },
+            { "id": "m3", "field": "dept", "transformation": "copy", "renameTo": "department" }
+          ]
+        }
+      }
+    ]
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the transform",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the transform fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+**Transformations:** `copy` (no change), `uppercase`, `lowercase`, `trim` (remove leading/trailing whitespace).
+
+**`keepOriginalFields`:** When `false`, only mapped fields appear in output. When `true`, unmapped fields pass through.
+
+**`renameTo`:** New field name. Empty string (`""`) keeps the original name.
+
+---
+
+## Group By (`core.action.transform.group-by`)
+
+```json
+{
+  "id": "groupByDept",
+  "type": "core.action.transform.group-by",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Group by Department" },
+  "inputs": {
+    "collection": "$vars.employees.output.items",
+    "operations": [
+      {
+        "id": "op1",
+        "type": "groupBy",
+        "config": {
+          "groupByField": "department",
+          "aggregations": [
+            { "id": "a1", "field": "", "operation": "count", "alias": "headcount" },
+            { "id": "a2", "field": "salary", "operation": "sum", "alias": "totalSalary" },
+            { "id": "a3", "field": "salary", "operation": "average", "alias": "avgSalary" },
+            { "id": "a4", "field": "salary", "operation": "min", "alias": "minSalary" },
+            { "id": "a5", "field": "salary", "operation": "max", "alias": "maxSalary" },
+            { "id": "a6", "field": "name", "operation": "collect", "alias": "names" },
+            { "id": "a7", "field": "name", "operation": "first", "alias": "firstHire" }
+          ]
+        }
+      }
+    ]
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the transform",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the transform fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+**Aggregation operations:**
+
+| Operation | Description | `field` required |
+| --- | --- | --- |
+| `count` | Number of items in group | No |
+| `sum` | Sum of numeric field | Yes |
+| `average` | Average of numeric field | Yes |
+| `min` | Minimum value | Yes |
+| `max` | Maximum value | Yes |
+| `collect` | Array of all field values | Yes |
+| `first` | First item's field value | Yes |
+| `last` | Last item's field value | Yes |
+
+---
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Filter passes all items through | Wrong condition name (e.g. `greater` instead of `greater_than`) | Use exact names: `equals`, `not_equals`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `contains`, `starts_with`, `ends_with`, `is_null`, `is_not_null` |
+| Filter silently returns empty array | Filter `value` holds an unresolved expression (`"$vars.x"`, `"=js:..."`, `"{$vars.x}"`) — Transform compares each item against that string literal | Replace with a literal scalar (`"value": 500`); expressions are not evaluated in filter `value`. If the threshold must be dynamic, do the filter in a Script node |
+| Collection is null/empty | `collection` was wrapped in `=js:` or set to an inline array literal instead of a plain variable path | Use a path such as `"$vars.loadCatalog.output.catalog"` or `"$vars.catalog"`; keep static arrays in a variable default or upstream node |
+| Map output missing fields | `keepOriginalFields: false` and field not in mappings | Add the field to mappings or set `keepOriginalFields: true` |
+| GroupBy produces empty groups | No items match the group field | Check `groupByField` matches actual field names in the data |

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

@@ -0,0 +1,47 @@
+# Transform Node — Planning
+
+## Node Types
+
+| Node Type | Description |
+| --- | --- |
+| `core.action.transform` | Chain multiple operations (filter, map, groupBy) in a single node |
+| `core.action.transform.filter` | Filter an array based on conditions |
+| `core.action.transform.map` | Transform each item (rename, convert fields) |
+| `core.action.transform.group-by` | Group items by a field with aggregations |
+
+## When to Use
+
+Use Transform nodes for declarative map, filter, or group-by on a collection — no custom code needed.
+
+### Selection Heuristics
+
+| Situation | Use Transform? |
+| --- | --- |
+| Standard filter/map/group-by on an array | Yes |
+| Custom logic, string manipulation, computation | No — use [Script](../script/planning.md) |
+| Iterate and perform actions per item (API calls, etc.) | No — use [Loop](../loop/planning.md) |
+
+## Ports
+
+All transform variants share the same port layout:
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `output`, `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 transformed collection
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `collection` | Yes | `$vars` reference to the input array |
+| `operations` | Yes | Array of operation objects (filter, map, or groupBy) |
+
+> The `collection` input accepts `$vars` references directly. Unlike condition expressions, the `=js:` prefix is optional — both `$vars.x` and `=js:$vars.x` work.
+
+> **Filter `value` is literal-only.** `core.action.transform.filter`'s per-filter `value` field does NOT resolve `$vars.x`, `=js:`, or brace-template expressions — any such expression ships as a string literal and the filter silently returns an empty array. Only literal scalars work (`500`, `"active"`, `true`). If the threshold must be dynamic, move the filter into a [Script](../script/planning.md) node; keep Transform for static-threshold filters, maps, and group-by. See [impl.md](impl.md#filter-coreactiontransformfilter) for details.

package/skills/uipath-maestro-flow/references/diagnose/CAPABILITY.md

@@ -0,0 +1,69 @@
+# Diagnose — Investigate failed or misbehaving flow runs
+
+Capability index for postmortem on a failed `flow debug` or deployed process run. Diagnose owns the diagnostic priority ladder (incidents → runtime variables → flow correlation → traces) and the catalog of known recurring failure modes (MST-9107, MST-9061, HITL-stuck, reused reference IDs, single-nested layout). Requires `uip login`.
+
+> **Where you came from / where to go next.** Diagnose is downstream of Operate (run faulted → diagnose) and points back to Author for the underlying fix (diagnose → re-author → re-ship). Re-running and lifecycle live in [operate/CAPABILITY.md](../operate/CAPABILITY.md); building/editing the `.flow` file lives in [author/CAPABILITY.md](../author/CAPABILITY.md).
+>
+> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, never invoke other skills automatically, AskUserQuestion dropdown pattern, **plain-English narration + granular `TodoWrite` (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are diagnose-scoped and apply on top.
+
+## When to use this capability
+
+- Triage a failed `flow debug` or deployed process run
+- Read incidents to identify the error category, message, and faulting element
+- Inspect runtime variable state at the time of failure
+- Map a faulting element ID back to a node in the `.flow` file
+- Stream verbose traces for execution timeline
+- Recognize known failure modes (MST-9107 missing `=js:`, MST-9061 format skipped, etc.)
+
+## Critical rules
+
+1. **Investigate in priority order — incidents → variables → flow correlation → traces.** Each step adds context; stop when you have enough to identify the root cause. Skipping ahead to traces is the most common mistake — they are verbose and last-resort. See [troubleshooting-guide.md](references/troubleshooting-guide.md).
+2. **Always include `--folder-key <FOLDER_KEY>` (`-f` shorthand) on `instance` and `incident get` commands.** Without it the command rejects the request before reaching the API. Get the folder key from `uip or folders list --output json` or from the job/process context. See [shared/cli-conventions.md](../shared/cli-conventions.md#6---folder-key-requirement).
+3. **Never call the underlying APIs directly — always use `uip` CLI commands.** The `instance` and `incident` subcommands are the supported diagnostic surface; direct API calls are not.
+4. **When the local `.flow` may differ from the deployed BPMN, fetch the deployed asset.** Use `uip maestro flow instance asset <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json` to see what actually ran. Do not assume your local file matches.
+
+## Workflow
+
+| Journey | Read |
+| --- | --- |
+| Triage a failed run (priority ladder) | [troubleshooting-guide.md](references/troubleshooting-guide.md) |
+| Look up a known failure mode | [failure-modes.md](references/failure-modes.md) |
+
+## Common tasks
+
+| I need to... | Read these |
+| --- | --- |
+| **Triage a failed flow run** | [troubleshooting-guide.md](references/troubleshooting-guide.md) |
+| **Find the error message and faulting element** | [troubleshooting-guide.md — Step 2 Fetch incidents](references/troubleshooting-guide.md#step-2--fetch-incidents) |
+| **See data state at the time of failure** | [troubleshooting-guide.md — Step 3 Fetch runtime variable state](references/troubleshooting-guide.md#step-3--fetch-runtime-variable-state) |
+| **Map a faulting element ID to a `.flow` node** | [troubleshooting-guide.md — Step 4 Correlate with the flow definition](references/troubleshooting-guide.md#step-4--correlate-with-the-flow-definition) |
+| **Pull verbose execution timeline** | [troubleshooting-guide.md — Step 5 Traces](references/troubleshooting-guide.md#step-5--traces-last-resort) |
+| **Identify a `vars.X.output.Y` literal-string failure** | [failure-modes.md — MST-9107](references/failure-modes.md#mst-9107--js-prefix-missing) |
+| **Identify misshapen Studio Web nodes** | [failure-modes.md — MST-9061](references/failure-modes.md#mst-9061--misshapen-rectangle-nodes-in-studio-web) |
+| **Diagnose a hung HITL node** | [failure-modes.md — HITL `completed` port unwired](references/failure-modes.md#hitl-completed-port-unwired) |
+| **Diagnose a connector silent fault** | [failure-modes.md — Reused reference ID](references/failure-modes.md#reused-reference-id--cross-connection-id-leakage) |
+| **Diagnose a publish/upload structural error** | [failure-modes.md — Single-nested layout](references/failure-modes.md#single-nested-layout) |
+| **Diagnose `Folder does not exist` on a resource node** | [failure-modes.md — Missing `bindings[]` on resource node](references/failure-modes.md#missing-bindings-on-resource-node) |
+| **Triage "validate passes, debug faults"** | [failure-modes.md — `flow validate` passes, `flow debug` faults](references/failure-modes.md#flow-validate-passes-flow-debug-faults) |
+| **Look up `instance` / `incident` CLI syntax** | [shared/cli-commands.md](../shared/cli-commands.md) + [troubleshooting-guide.md — CLI command reference](references/troubleshooting-guide.md#cli-command-reference) |
+
+## Anti-patterns
+
+- **Never start with traces.** They are verbose and contain the full execution timeline — useful only when incidents and variables are insufficient. Start with incidents (Step 2 of the priority ladder).
+- **Never call the underlying APIs directly.** Always use `uip maestro flow instance` / `incident` / `job` subcommands. Direct API calls bypass the supported diagnostic surface.
+- **Never assume the local `.flow` matches the deployed BPMN.** If there's any chance the deployed flow differs (a republish since the local edit, a different branch, a different solution version), fetch `instance asset` to see what actually ran. Otherwise your correlation between faulting element and `.flow` node will mislead you.
+- **Never skip the `--folder-key` flag** on `instance` or `incident get` commands. The command rejects the request before reaching the API; the failure looks like a CLI error but is really a missing argument.
+
+## References
+
+### Diagnose-scoped
+
+- [troubleshooting-guide.md](references/troubleshooting-guide.md) — diagnostic priority ladder (incidents → variables → flow correlation → traces) and full `instance` / `incident` CLI reference
+- [failure-modes.md](references/failure-modes.md) — pattern catalog for known recurring failures: MST-9107, MST-9061, HITL-stuck, reused reference IDs, single-nested layout, "validate passes / debug faults"
+
+### Cross-capability (shared)
+
+- [shared/cli-commands.md](../shared/cli-commands.md) — flat CLI lookup including `instance` / `incident` / `job` subcommands
+- [shared/cli-conventions.md](../shared/cli-conventions.md) — `--folder-key` requirement, login state, JSON output shape
+- [shared/file-format.md](../shared/file-format.md) — to correlate faulting element IDs back to `.flow` nodes
+- [shared/node-output-wiring.md](../shared/node-output-wiring.md) — referenced from MST-9107 failure mode