@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,252 @@
+# Transform Node — Implementation
+
+## Node Types and Registry Validation
+
+Supported node types:
+
+- `core.action.transform` — generic; chains operations
+- `core.action.transform.filter` — filter only
+- `core.action.transform.map` — map only
+- `core.action.transform.group-by` — group-by only
+
+Run:
+
+```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 each definition has input port `input`, output ports `output` and `error`, and required inputs `collection` and `operations`. Set each instance's `typeVersion` to the matching response's `version`; do not hardcode it.
+
+For add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the node-specific `inputs` and `model` structures below.
+
+Every transform uses this output schema:
+
+```json
+"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"
+  }
+}
+```
+
+## Collection Input and Output Shape
+
+`inputs.collection` is a transform-specific path containing the array. Use a plain path:
+
+```json
+"collection": "$vars.orders.output.items"
+```
+
+Never use `=js:` or an inline array literal:
+
+```json
+"collection": "=js:$vars.orders.output.items"
+```
+
+```json
+"collection": "=js:[{\"title\":\"Example\"}]"
+```
+
+The runtime resolves the path as a lookup such as `vars.orders.output.items`; `=js:` and inline JSON/JS literals resolve to an empty collection. For static data, put the array in a workflow variable `defaultValue` or emit it from an upstream static-data/script node, then reference that variable or node output.
+
+A transform's `$vars.<transformNode>.output` is a bare array: filter returns surviving elements, map returns mapped elements, and group-by returns group objects (`{<groupByField>, <alias>…}`). Chain transforms from `.output`, never `.output.items`; `.items` becomes `undefined` and silently yields empty input. `.items`/`.body.items` below refer only to HTTP-body or variable shapes.
+
+```json
+"collection": "$vars.filterHighViewDays.output"
+```
+
+In a Script node, read an element field as `$vars.groupByNode.output[0].totalViews`.
+
+## Generic Transform (`core.action.transform`)
+
+Operations run in order; each feeds 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" }
+  }
+}
+```
+
+Conditions: `equals`, `not_equals`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `contains`, `starts_with`, `ends_with`, `is_null`, `is_not_null`.
+
+Operations: `and` (all conditions), `or` (any condition).
+
+`filter.value` is literal-only. It does not evaluate `$vars`, `=js:`, or brace templates; `"$vars.threshold"`, `"=js:$vars.threshold"`, and `"{$vars.threshold}"` are compared as literal strings and silently produce an empty result. Use literal scalars such as `500`, `"active"`, or `true`. For dynamic thresholds, filter in a [Script](../script/impl.md) node or hoist the literal into the flow design. `field` accepts dot-paths such as `order.amount`.
+
+## 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`, `uppercase`, `lowercase`, `trim`.
+
+`keepOriginalFields: false` outputs only mapped fields; `true` passes through unmapped fields. `renameTo` changes the field name; `""` 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 |
+
+**One figure over the whole collection.** Aggregations are group-scoped, so a grand total needs a single group: set `groupByField: ""`. The node returns a one-element array; read the aggregate at `output[0].<alias>`.
+
+```json
+{ "id": "op1", "type": "groupBy", "config": {
+    "groupByField": "",
+    "aggregations": [{ "id": "a1", "field": "views", "operation": "sum", "alias": "total" }] } }
+```
+
+The group object also carries a `value` key holding the first row — read the alias, not `value`.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Filter passes all items through | Wrong condition name, such as `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 | `value` contains an unresolved expression; Transform compares it as a literal string | Use a literal scalar such as `"value": 500`; for dynamic thresholds, use a Script node |
+| Collection is null/empty | `collection` uses `=js:` or an inline array literal | Use a plain path such as `"$vars.loadCatalog.output.catalog"` or `"$vars.catalog"`; store static arrays in a variable default or upstream node |
+| Map output missing fields | `keepOriginalFields: false` and the field is unmapped | Add the field to mappings or set `keepOriginalFields: true` |
+| GroupBy produces empty groups | No items match `groupByField` | Check that `groupByField` matches the actual data fields |
+| Need one total across every row, not per group | Aggregations are group-scoped | Set `groupByField: ""` for a single group; read `output[0].<alias>` |
+| Chained transform gets empty input although upstream had rows | Used `$vars.<transform>.output.items`; transform output is a bare array | Use `$vars.<transform>.output`; see [Output Shape](#collection-input-and-output-shape) |

package/skills/uipath-maestro-flow/references/author/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,73 @@
+# 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 recurring failure modes (missing `=js:`, misshapen nodes, HITL-stuck, reused reference IDs, single-nested layout). Requires `uip login`.
+
+> **Navigation.** Diagnose follows Operate when a run faults and points to Author for the fix. Re-running and lifecycle are in [operate/CAPABILITY.md](../operate/CAPABILITY.md); building or editing `.flow` files is in [author/CAPABILITY.md](../author/CAPABILITY.md).
+>
+> **Inherited rules:** use `--output json` and prefer `--output-filter` for extraction; do not run `flow debug` without consent; never invoke other skills automatically; use the dropdown question pattern; provide plain-English narration and a granular progress list only when the user asks for verbosity, and remain silent by default. These rules apply in addition to the rules below.
+
+## When to use this capability
+
+- Triage a failed `flow debug` or deployed process run.
+- Read incidents for the error category, message, and faulting element.
+- Inspect runtime variables at failure time.
+- Map a faulting element ID to a `.flow` node.
+- Stream verbose execution traces.
+- Recognize known failures, including missing `=js:` and format skips.
+
+## Critical rules
+
+0. **Read the faulted `flow debug` response before any other call — never re-run debug to "see the error again".** See [troubleshooting-guide.md — Step 0](troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have).
+1. **Investigate in order: incidents → variables → flow correlation → traces.** Stop when the root cause is identified; traces are verbose and last-resort. See [troubleshooting-guide.md](troubleshooting-guide.md).
+2. **Always include `--folder-key <FOLDER_KEY>` (`-f` shorthand) on `instance` and `incident get` commands.** Run `uip or folders list --output json` to obtain the folder key, or obtain it from the job/process context. See [shared/cli-conventions.md](../shared/cli-conventions.md#6---folder-key-requirement).
+3. **Never call underlying APIs directly.** Run supported `uip` CLI commands; `instance` and `incident` are the diagnostic surface.
+4. **When the local `.flow` may differ from the deployed BPMN, fetch the deployed asset.** Run `uip maestro flow instance asset <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json` and correlate against what actually ran.
+
+## Workflow
+
+| Journey | Read |
+| --- | --- |
+| Triage a failed run (priority ladder) | [troubleshooting-guide.md](troubleshooting-guide.md) |
+| Look up a known failure mode | [failure-modes.md](failure-modes.md) |
+
+## Common tasks
+
+| Need | Read |
+| --- | --- |
+| Triage a failed flow run | [troubleshooting-guide.md](troubleshooting-guide.md) |
+| An in-solution chat agent shows as autonomous | The registry builds that node from the sibling project's `agent.json` and falls back to autonomous when it cannot read it. `--log-level debug` names the reason ("Unparseable agent.json" / "No readable agent.json"); nothing else reports it. See [conversational-agent/impl.md](../author/plugins/conversational-agent/impl.md#resolve-the-agent) |
+| A chat flow "hangs" or times out during debug | Not a fault. `flow debug` hands a `core.trigger.conversation` flow off rather than running it, and a flow parked on `wait-for-message` is waiting for a user message that no headless run will send. Drive it from a chat UI — Studio Web or the UiPath Maestro VS Code extension. See [conversational-agent/impl.md](../author/plugins/conversational-agent/impl.md#debug--the-cli-hands-off) |
+| Read the cause out of a faulted `flow debug` response | [troubleshooting-guide.md — Step 0](troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have) |
+| Find the error message and faulting element | [troubleshooting-guide.md — Step 2 Fetch incidents](troubleshooting-guide.md#step-2--fetch-incidents) |
+| See data state at failure time | [troubleshooting-guide.md — Step 3 Fetch runtime variable state](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](troubleshooting-guide.md#step-4--correlate-with-the-flow-definition) |
+| Pull verbose execution timeline | [troubleshooting-guide.md — Step 5 Traces](troubleshooting-guide.md#step-5--traces-last-resort) |
+| Identify a `vars.X.output.Y` literal-string failure | [failure-modes.md — `=js:` prefix missing](failure-modes.md#js-prefix-missing) |
+| Identify misshapen Studio Web nodes | [failure-modes.md — misshapen nodes](failure-modes.md#misshapen-rectangle-nodes-in-studio-web) |
+| Diagnose a hung HITL node | [failure-modes.md — HITL outcome port unwired](failure-modes.md#hitl-outcome-port-unwired) |
+| Diagnose a connector silent fault | [failure-modes.md — Reused reference ID](failure-modes.md#reused-reference-id--cross-connection-id-leakage) |
+| Diagnose a publish/upload structural error | [failure-modes.md — Single-nested layout](failure-modes.md#single-nested-layout) |
+| Diagnose `Folder does not exist` on a resource node | [failure-modes.md — Missing `bindings[]` on resource node](failure-modes.md#missing-bindings-on-resource-node) |
+| Triage "validate passes, debug faults" | [failure-modes.md — `flow validate` passes, `flow debug` faults](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](troubleshooting-guide.md#cli-command-reference) |
+
+## Anti-patterns
+
+- **Do not start with traces.** Start with incidents (Step 2), then variables, flow correlation, and traces only if needed.
+- **Do not call underlying APIs directly.** Run `uip maestro flow instance` / `incident` / `job` subcommands.
+- **Do not assume the local `.flow` matches the deployed BPMN.** If a republish, branch, or solution-version difference is possible, run `instance asset` before correlating IDs.
+- **Do not omit `--folder-key`** from `instance` or `incident get`; the command rejects the request before reaching the API.
+
+## References
+
+### Diagnose-scoped
+
+- [troubleshooting-guide.md](troubleshooting-guide.md) — diagnostic priority ladder (incidents → variables → flow correlation → traces) and full `instance` / `incident` CLI reference
+- [failure-modes.md](failure-modes.md) — recurring failures: missing `=js:`, misshapen nodes, HITL-stuck, reused reference IDs, single-nested layout, and "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) — correlate faulting element IDs to `.flow` nodes
+- [shared/node-output-wiring.md](../shared/node-output-wiring.md) — referenced from the `=js:` prefix-missing failure mode