@uipath/skills 1.195.0

package/skills/uipath-maestro-case/references/bindings-and-expressions.md

@@ -0,0 +1,171 @@
+# Bindings & Expressions Reference
+
+How to wire values into task inputs — expression prefixes, cross-task output references, and direct JSON editing.
+
+## Two Binding Modes
+
+Every task input is wired using one of two modes. Pick based on the source of the value.
+
+| Mode | Tasks.md syntax | Implementation |
+|------|-----------------|----------------|
+| **Literal or expression** | `input = "<value>"` | Write `"<value>"` to `task.data.inputs[i].value` in caseplan.json |
+| **Cross-task reference** | `input <- "Stage"."Task".output` | Resolve source output's `var` → write `"=vars.<var>"` to target input's `value` |
+
+For the full JSON shapes and binding procedure, see [plugins/variables/io-binding/impl-json.md](plugins/variables/io-binding/impl-json.md).
+
+For connector tasks, input values are written directly to `caseplan.json` — see [plugins/tasks/connector-activity/impl-json.md](plugins/tasks/connector-activity/impl-json.md).
+
+## Expression Prefixes
+
+When using the literal/expression mode, the `--value` string can start with one of these prefixes to resolve dynamically at runtime. Plain strings without a prefix are treated as literals.
+
+| Prefix | Meaning | Example |
+|--------|---------|---------|
+| `=metadata.` | Case metadata field | `=metadata.amount` |
+| `=js:` | Inline JavaScript expression | `=js:new Date().toISOString()` |
+| `=vars.` | Case-level variable | `=vars.inbox_config` |
+| `=bindings.` | Resource binding (connection, queue, trigger) | `=bindings.slackConnection` |
+| `=datafabric.` | Data Fabric entity field | `=datafabric.Customer.id` |
+| `=orchestrator.JobAttachments` | Orchestrator job attachments | `=orchestrator.JobAttachments[0]` |
+| `=response` | The response object from a previous HTTP step | `=response.body` |
+| `=result` | The result of the previous task | `=result.status` |
+| `=Error` | Error object from a failed step | `=Error.message` |
+| `=jsonString:` | Serialize the following expression to a JSON string | `=jsonString:vars.config` |
+
+> Plain strings (no prefix) are literal values. `"hello"` is literally the string `hello`, not an expression.
+
+> The prefix tells you WHAT the value refers to. The **sink** tells you HOW to wrap it — see [§ Canonical form per sink](#canonical-form-per-sink) below.
+
+## Canonical form per sink
+
+Every `=`-prefixed value in `caseplan.json` is dispatched to one of two runtime evaluators based on the sink it lands in. **The wrap form must match the sink** — wrong wrap is a silent runtime fault (the literal string arrives at the consumer instead of the resolved value).
+
+### Two evaluator paths
+
+| Path | Trigger | Capabilities |
+|---|---|---|
+| **Lookup** | Value starts with `=vars.<id>` or `=bindings.<id>` | Strip prefix, look up by id, return value. NO operators, NO dotted access, NO `=metadata.` |
+| **JS eval** | Value starts with `=js:<expr>` | Full JS evaluation. Predefined namespaces: `vars`, `response`, `bindings`, `iterator`, `metadata`. Operators, function calls, dotted access all work. **A condition / rule `conditionExpression` can reference only case variables (`vars.X`) and `metadata`** — there is no `event` namespace (referencing `event` errors with "event not found"). For event-payload gating: in-rule extract-then-gate (extract `response.X -> caseVar` AND gate `=js:vars.caseVar…` on the SAME rule) is **NOT supported at runtime** — the case-backend evaluates the gate against the pre-extract value. Place the case-state gate on the DOWNSTREAM stage-entry / task-entry condition that follows the connector rule. |
+
+`data.inputs[].value` on non-connector tasks runs **lookup** when the value matches `^=vars\.\w+$` or `^=bindings\.\w+$`; **JS eval** otherwise. Connector body fields, filter expressions, and condition expressions ALL run **JS eval** — they require `=js:` wrap regardless of value shape.
+
+### Form by sink (the table)
+
+| Sink | Plain-ref form (when applicable) | Expression form |
+|---|---|---|
+| **Non-connector task `data.inputs[].value`** | `=vars.<id>` / `=bindings.<id>` (single identifier — no dots, no operators) | `=js:<expr>` (everything else: `=metadata.*`, dotted access, operators, function calls) |
+| **Connector body field — dot-notation** (curated connectors) | (no plain branch) | `=js:(<expr>)` — uniform wrap, parens always |
+| **Connector trigger filter expression** (`body.filters.expression`) with variable refs | n/a | `` =js:`<JMESPath with ${vars.X} interpolations>` `` |
+| **Connector trigger filter expression** plain literal (no variables) | Unwrapped CEQL/JMESPath text | n/a |
+| **`conditionExpression`** (stage entry/exit, task entry, case exit, trigger rules, edge transitions) | (no plain branch) | `=js:<expr>` — no outer parens; sub-clauses get manual parens when combining via `&&` / `\|\|` |
+| **SLA rule `expression`** | (no plain branch) | `=js:<expr>` (default: `=js:true`) |
+| **Task output `source` / `target`** | `=vars.<varId>` / `=<rawFieldName>` | n/a (always plain) |
+| **Binding refs in `data.context`, `caseShape.context`** | `=bindings.<id>` | n/a |
+
+> **JIT object mode (out of scope for this version).** When an activity's `inputMetadata.inputMode === "jitObject"` (synthetic HTTP request bodies, generic body-passthrough activities), the whole connector body becomes one `=js:({...})` expression with bare JS variable references inline. The skill currently routes synthetic HTTP through `queryParameters` instead. JIT-mode authoring is not documented in this version.
+
+### Conservative rule for `=metadata.X`
+
+The lookup-path resolver has NO `=metadata.` branch — plain `=metadata.X` is NOT resolved at runtime. **Always wrap as `=js:metadata.X`** (or `=js:(metadata.X)` if the sink requires parens). The FE design-time picker may classify `=metadata.X` as "variable" type, but that's a UI hint, not a runtime contract.
+
+### Planner-emit form
+
+The planner emits `tasks.md` using SDD-natural references — `=vars.X`, `=metadata.X`, `=bindings.X`, cross-task `<- "Stage"."Task".out` (verbatim, unresolved). Other `=`-prefixed forms (`=response.X`, `=Error.X`, `=datafabric.X`, `=orchestrator.JobAttachments`) also pass through to impl for per-sink wrap; see [Expression Prefixes](#expression-prefixes) for the full set. The implementation step rewrites to the canonical sink form when constructing `caseplan.json`. Detail: [plugins/variables/io-binding/planning.md](plugins/variables/io-binding/planning.md) and each plugin's `impl-json.md`.
+
+## Cross-Task References
+
+Cross-task references wire the output of an earlier task into an input of a later task. The planning syntax uses **names** (human-readable), which the implementation phase resolves to variable IDs via direct JSON lookup.
+
+### Planning syntax (in `tasks.md`)
+
+```
+input_name <- "Stage Name"."Task Name".output_name
+```
+
+- `Stage Name` — the `display-name` of the containing stage (exactly as written in a `Create stage "<name>"` task)
+- `Task Name` — the `display-name` of the source task (exactly as written in an `Add <type> task "<name>"` task)
+- `output_name` — a named output field from the source task
+
+### Discovering output names
+
+Run `tasks describe` during planning to list available outputs for a given task type:
+
+```bash
+uip maestro case tasks describe --type <type> --id "<taskTypeId>" --output json
+uip maestro case tasks describe --type connector-activity --id "<typeId>" --connection-id "<uuid>" --output json
+```
+
+Output names appear in the response under the output schema. Record them in the source task's `outputs:` field in `tasks.md` so downstream references can be validated.
+
+### Validation rule
+
+Every cross-task reference in `tasks.md` MUST point to:
+1. A stage that exists (created by an earlier `Create stage "..."` task).
+2. A task inside that stage that exists (created by an earlier `Add ... task "..." to "<stage>"` task).
+3. An output name listed in that task's `outputs:` field.
+
+Missing any of the three → halt planning and ask the user; do not fabricate.
+
+### Implementation translation
+
+The execution phase resolves names to IDs by reading caseplan.json:
+
+```python
+# Pseudo-code:
+src_stage = find_node_by_label(nodes, "Stage Name")
+src_task  = find_task_by_name(src_stage, "Task Name")
+src_output = find_output_by_name(src_task, "output_name")
+target_input.value = f"=vars.{src_output['var']}"
+# Write updated caseplan.json back to disk
+```
+
+See [plugins/variables/io-binding/impl-json.md](plugins/variables/io-binding/impl-json.md) for the full procedure.
+
+## Examples
+
+### Literal and expression inputs
+
+```markdown
+## T10: Add api-workflow task "Fetch Inbox" to "Triage"
+- inputs:
+  - inbox_config = "=vars.inbox_config"
+  - po_patterns  = "=vars.po_patterns"
+  - max_results  = "50"
+  - requested_at = "=js:new Date().toISOString()"
+```
+
+### Cross-task reference
+
+```markdown
+## T11: Add agent task "Classify Emails" to "Triage"
+- inputs:
+  - emails <- "Triage"."Fetch Inbox".emails
+  - customer_id <- "Triage"."Fetch Inbox".customer_id
+- outputs: category, priority_score
+```
+
+### Mixed inputs (HITL/action)
+
+```markdown
+## T12: Add action task "Review Classification" to "Triage"
+- recipient: approver@corp.com
+- priority: High
+- inputs:
+  - classification <- "Triage"."Classify Emails".category
+  - priority       <- "Triage"."Classify Emails".priority_score
+  - deadline       = "=js:new Date(Date.now() + 86400000).toISOString()"
+- outputs: decision, comments
+```
+
+## Anti-Patterns
+
+- **Mixing `--value` and `--source-*` in the same bind.** The CLI rejects this. Pick one mode per input.
+- **Referencing a future task's output.** Cross-task references must target an earlier task in execution order.
+- **Fabricating output names.** Always discover via `tasks describe`. A typo becomes a runtime null, not a validation error.
+- **Plain-string where expression was intended.** `"metadata.amount"` (no `=`) is the literal string `metadata.amount`, not a reference. Always include the `=` prefix for dynamic values.
+- **Nesting expressions inside literals.** `"$metadata.amount"` or `"{{ amount }}"` do not work. Use `=metadata.amount` directly as the full value.
+- **Plain `=vars.X` inside connector body JSON.** The runtime does NOT evaluate plain prefix refs in connector body sinks — they arrive at the API as literal strings. Wrap as `=js:(vars.X)`. See [§ Canonical form per sink](#canonical-form-per-sink).
+- **Plain `=metadata.X` anywhere.** The lookup-path resolver has no `=metadata.` branch. Always wrap as `=js:metadata.X` (or `=js:(metadata.X)` for connector body / parens-required sinks).
+- **Dotted access via plain prefix.** `=vars.user.email` looks up a variable with id literally `user.email` and fails. Use `=js:vars.user.email`.
+- **`=js:(...)` outer parens on `conditionExpression`.** Conditions use bare `=js:<expr>` per FE convention. Sub-clause parens go inside when combining: `=js:(vars.X) && (vars.Y)` — outer wrap stays bare.
+- **Manually building filter-expression strings.** For filter sinks, author a structured FilterTree with `isLiteral: true` values when possible. Variable-bearing filters use `` =js:`<template>` `` with `${vars.X}` interpolations — see [connector-trigger-common.md](connector-trigger-common.md).

package/skills/uipath-maestro-case/references/bindings-v2-sync.md

@@ -0,0 +1,142 @@
+# bindings_v2.json Sync
+
+Shared procedure for keeping `bindings_v2.json` in sync after any plugin writes to the bindings array in `caseplan.json`.
+
+## Schema-dependent source path
+
+Read `Schema:` header from `tasks.md` per Rule 18.
+
+| Schema | Source path in `caseplan.json` |
+|---|---|
+| **v19** | `root.data.uipath.bindings[]` |
+| **v20** | `bindings[]` *(top level)* |
+
+Field shape inside the array is identical across schemas — only the source path for the regeneration read differs. Output `bindings_v2.json` shape is unchanged across schemas.
+
+## When to Run
+
+**Batched, not per-task.** `bindings_v2.json` is only consumed by `uip solution resource refresh` (which runs once before upload/debug). No intermediate step reads it. Regenerating after every task wastes Read→convert→Write cycles on a growing file.
+
+Run at these three points only:
+
+1. **End of Phase 2 Step 9** (after all non-connector tasks written) — covers all process/agent/rpa/action/api-workflow/case-management bindings
+2. **End of Phase 3 Step 9.7** (after all connector tasks populated) — adds Connection bindings + populates IS cache for tasks
+3. **End of Phase 3 Step 10** (after all connector condition RULES written across the 4 scopes — stage-entry, stage-exit, case-exit, task-entry) — adds Connection bindings + populates IS cache for rules. Required because connector rules are written in Step 10 (conditions), not Step 9.7 (tasks); without this third sync point, rule-introduced Connection/Folder bindings + IS-cache entries wouldn't land until the post-Phase-3 catch-all, and `resource refresh` would miss them.
+
+Individual task / rule plugins write bindings to `caseplan.json` per-target as normal (path per § Schema-dependent source path above). The batch regeneration reads the full bindings array once from the schema-appropriate path and converts everything in one pass.
+
+---
+
+## § Regenerate bindings_v2.json
+
+After writing bindings (to the schema-appropriate path), regenerate `bindings_v2.json`. This file uses a **different format**: `caseplan.json` stores two entries per resource (one per property), `bindings_v2.json` stores one entry per resource with properties nested under `value`.
+
+### Procedure
+
+1. Read the bindings array from `caseplan.json` — `root.data.uipath.bindings[]` in v19, top-level `bindings[]` in v20
+2. Group bindings by `resourceKey` — entries sharing the same key belong to one resource
+3. For each group, produce one resource entry using the shapes below
+4. Write the full file (always overwrite, never append) to `<SolutionDir>/<ProjectName>/bindings_v2.json`
+
+### Non-connector resource entry
+
+```json
+{
+  "resource": "<resource>",
+  "key": "<resourceKey>",
+  "value": {
+    "name": { "defaultValue": "<name binding default>" },
+    "folderPath": { "defaultValue": "<folderPath binding default>" }
+  },
+  "metadata": { "subType": "<resourceSubType — omit metadata key if none>" }
+}
+```
+
+### Connector resource entry
+
+```json
+{
+  "resource": "Connection",
+  "key": "<connectionId>",
+  "value": {
+    "connectionId": { "defaultValue": "<connectionId>" },
+    "folderKey": { "defaultValue": "<folderKey>" }
+  },
+  "metadata": { "connector": "<connectorKey>" }
+}
+```
+
+> **Known CLI bug:** `syncConnectionResources` reads `value.connectionId` (lowercase c) but `flow-schema` writes `value.ConnectionId` (uppercase C). Use **lowercase `connectionId`** until fixed.
+
+File envelope: `{ "version": "2.0", "resources": [ /* one entry per resource */ ] }`
+
+---
+
+## § Populate IS connection cache
+
+`uip solution resource refresh` reads a local IS cache that connector plugins must populate after `get-connection`. Applies to all three connector-resolving paths: connector **tasks** (Step 9.7), connector **triggers** (Step 8), and connector **condition rules** in any of the 4 scopes (Step 10).
+
+**Path:** `~/.uipath/cache/integrationservice/<connectorKey>/connections.json`
+
+**Shape — bare JSON array:**
+
+```json
+[
+    {
+        "id": "<connectionId>",
+        "name": "<connectionName>",
+        "connectorKey": "<connectorKey>",
+        "connectorName": "<connectorName>",
+        "folderKey": "<folderKey>",
+        "folderName": "<folderName>"
+    }
+]
+```
+
+### Field sources
+
+| Field | Source | Plugin step |
+|---|---|---|
+| `id` | `connection-id` from `tasks.md` | Planning |
+| `name` | `.Data.Connections[selected].name` from `get-connection` | Step 1 |
+| `connectorKey` | `connector-key` from `tasks.md` | Planning |
+| `connectorName` | `.Data.Connections[selected].connector.name` from `get-connection` | Step 1 |
+| `folderKey` | `.Data.Connections[selected].folder.key` from `get-connection` | Step 1 |
+| `folderName` | `.Data.Connections[selected].folder.name` from `get-connection` | Step 1 |
+
+### Procedure
+
+After `get-connection` succeeds (Step 1), write or merge the cache:
+
+1. Read existing cache at the path above (may not exist — start with `[]`)
+2. If an entry with the same `id` already exists, skip
+3. Otherwise append the new entry
+4. Write the file as a bare JSON array (NOT wrapped in `{ cachedAt, data }`)
+
+```bash
+mkdir -p ~/.uipath/cache/integrationservice/<connectorKey>
+```
+
+> Workaround for CLI bugs: (1) tenant-ID prefix in cache path, (2) wrapped `{ cachedAt, data }` format. Direct write bypasses both.
+
+---
+
+## What `resource refresh` produces
+
+With `bindings_v2.json` and IS cache in place, `uip solution resource refresh` creates:
+
+| Input | Output | Purpose |
+|---|---|---|
+| Non-connector bindings in `bindings_v2.json` | `resources/solution_folder/process/` files | Resource declarations imported from Orchestrator |
+| Connection binding in `bindings_v2.json` + IS cache | `resources/solution_folder/connection/<connectorKey>/<name>.json` | Connection resource declaration |
+| Both | `userProfile/<userId>/debug_overwrites.json` | Maps abstract resources to Orchestrator instances for debug |
+
+All three required for `uip solution upload` and `uip maestro case debug` to work without "Resource is not configured" warnings.
+
+---
+
+## Cleanup on task or rule removal
+
+When any task or connector condition rule is removed and its root bindings are pruned (per [case-editing-operations.md](case-editing-operations.md) § Delete a node / § Delete a connector condition rule):
+
+1. After pruning root bindings, regenerate `bindings_v2.json` from the updated array.