@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-human-in-the-loop/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: uipath-human-in-the-loop
-description: "UiPath Human-in-the-Loop / HITL node authoring — building approval gates, escalations, write-back validation, and data enrichment checkpoints in Flow, Maestro, or Coded Agents. NOT for managing, reassigning, or monitoring tasks at runtime (use uipath-tasks for that)."
+description: "UiPath Human-in-the-Loop / HITL node authoring — building approval gates, escalations, write-back validation, and data enrichment checkpoints in Flow, Maestro, Case Management, or Coded Agents. NOT for managing, reassigning, or monitoring tasks at runtime (use uipath-tasks for that)."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 ---
 
 # UiPath Human-in-the-Loop Assistant
 
-Recognizes when a business process needs a human decision point, designs the task schema through conversation, and wires the HITL node into the automation — Flow, Maestro, or Agent.
+Recognizes when a business process needs a human decision point, designs the task schema through conversation, and wires the HITL node into the automation — Flow, Maestro, Case Management, or Agent.
 
 > **Coded agents:** for wiring HITL inside a coded agent, use the `uipath-agents` skill — see `skills/uipath-agents/references/coded/capabilities/human-in-the-loop.md`.
 
@@ -72,6 +72,11 @@ Run these checks in order:
 # Check for a .flow file (Flow project)
 find . -name "*.flow" -maxdepth 4 | head -5
 
+# Check for a Case Management project. The on-disk filename varies
+# (caseplan.json, or content/<name>.json.bpmn under a `uip maestro case init`
+# project) — detect by content marker, not by filename.
+grep -rl '"case-management:root"' --include="*.json*" . 2>/dev/null | head -3
+
 # Check for agent.json (Low-Code Agent project)
 find . -name "agent.json" -maxdepth 4 | head -3
 
@@ -82,6 +87,7 @@ find . -name "*.bpmn" -maxdepth 4 | head -3
 | Found | Surface | How HITL is added |
 |---|---|---|
 | `.flow` file | **Flow** | Write node JSON directly — see reference docs |
+| `caseplan.json` (any `*.json` with `root.type: "case-management:root"`) | **Case** | Write `action` task into stage — see [hitl-casetask-action.md](references/hitl-casetask-action.md) |
 | `agent.json` | **Low Code Agent** | Escalation CLI in-flight — guide manually for now |
 | `.bpmn` (Maestro) | **Maestro** | Write the `UserTask` XML directly — see Step 5 Surface: Maestro |
 
@@ -142,7 +148,11 @@ Wait for confirmation. Do not proceed to schema design until the user confirms.
 
 ## Step 3 — Choose Task Type
 
-Present the user with three options. Do not choose on their behalf or perform any registry search.
+**The options differ by surface.** Present the options for the detected surface and confirm before doing anything.
+
+### Surface: Flow
+
+Present three options. Do not choose on behalf of the user or perform any registry search.
 
 | # | Option | Node type | Description |
 |---|---|---|---|
@@ -171,6 +181,34 @@ Present the user with three options. Do not choose on their behalf or perform an
 
 ---
 
+### Surface: Case
+
+Present two options. Do not choose on behalf of the user or pull the registry.
+
+| # | Option | Fingerprint | Description |
+|---|---|---|---|
+| 1 | **QuickForm (file-based schema)** | separate `<TaskLabel>.hitl.json` file + `hitlType: "quick"` context entry in the action task | Structured form fields in a `.hitl.json` file alongside `caseplan.json`. Action Center renders fields at runtime. No deployed app needed. |
+| 2 | **App-based action task** | `data.name` and `data.folderPath` as `=bindings.<id>` references + `data.actionCatalogName` | Uses a deployed Action Center app with custom input/output fields. Requires the app to exist in Orchestrator. |
+
+> **If the user is unsure or says "just pick one":** Default to QuickForm. Say: "I'll use QuickForm — it's the quickest to set up, supports structured form fields, and doesn't need a deployed app. You can upgrade to an app-based task later if you need a custom UI layout."
+
+> **Build vs design time.** QuickForm in case management must round-trip both ways: the JSON written here is what Studio Web's case designer reads (design time), and what `uip maestro case validate` + Action Center render at runtime (build time). Always validate after writing.
+
+| User selects | Next step |
+|---|---|
+| QuickForm (file-based schema) | Read [references/hitl-casetask-action.md — Path 1](references/hitl-casetask-action.md#path-1--quickform-file-based-schema-no-deployed-app), then continue with Step 4 |
+| App-based action task → ask: "What is the name of the deployed Action Center app?" | Read [references/hitl-casetask-action.md — Path 2](references/hitl-casetask-action.md#path-2--app-based-action-task-deployed-action-center-app), then continue with Step 4 |
+
+**Fallback rules:**
+
+| Path | Blocker | Response |
+|---|---|---|
+| App-based | App not found in registry or `action-apps-index.json` | "I couldn't find that app. Would you like to try a different name, or fall back to QuickForm while the app is prepared?" |
+| QuickForm | Schema design rejected on validate (e.g. duplicate field IDs, missing primary outcome) | Surface the validator's error, fix the schema, re-show to user, validate again. Apply Step 4b checks. |
+| Any | Auth expired (401 on API call) | "The session looks expired — run `uip login` to refresh your credentials, then retry." |
+
+---
+
 ## Step 4 — Common configuration
 
 | Timeout | "How long before the task times out if nobody acts? (default: 24 hours)" |
@@ -178,9 +216,9 @@ Present the user with three options. Do not choose on their behalf or perform an
 
 ---
 
-## Step 4b — Schema Design Rules (QuickForm only)
+## Step 4b — Schema Design Resilience (QuickForm — Flow and Case)
 
-Apply these rules unconditionally while designing the schema.
+Apply these checks while designing the schema before confirming with the user. Applies equally to Flow QuickForm nodes and Case QuickForm action tasks — same `fields[]` + `outcomes[]` shape, same `direction` semantics.
 
 ### Field direction
 
@@ -196,14 +234,15 @@ Pick direction based on what the human does with the field:
 
 ### Field types
 
-Use the JS/JSON type that fits the field: `string`, `number`, `boolean`, `date`, or `file`. These are the only valid values — do not use `text`.
+Use the JS/JSON type that fits the field: `string`, `number`, `boolean`, `date`, or `file`. These are the only valid values — do not use `text`. Case also supports `datetime` (distinct from `date`, for full date+time values) — see [hitl-casetask-action.md](references/hitl-casetask-action.md) for the Case-specific type table.
 
 ### Vague or incomplete schema descriptions
 
 If the user says something like "just add some fields" or "use whatever makes sense":
 
-1. Infer sensible defaults from the upstream data and downstream needs visible in the `.flow` file.
-2. If there are no upstream nodes to bind to (flow is just a trigger), use output-direction fields only.
+1. Infer sensible defaults from the upstream data and downstream needs visible in the `.flow` file (Flow) or in `caseplan.json` upstream task `outputs[]` and `root.data.uipath.variables` (Case).
+2. Show the proposed schema explicitly before writing: "Here's what I'm proposing — let me know if you want to change anything."
+3. If there is nothing upstream to bind to (Flow with only a trigger; Case with this as the first task), use output-direction fields only and note: "There are no upstream values to pull data from, so the reviewer will fill in all fields from scratch."
 
 ### Empty field labels block validation
 
@@ -266,6 +305,27 @@ After writing, validate:
 uip maestro flow validate <file> --output json
 ```
 
+### Surface: Case
+
+Read the `caseplan.json` to identify the target stage. Write an `action` task directly into `stage.data.tasks[lane][]`. **Direct JSON write is the only supported method** — the `uipath-maestro-case` skill ships no `hitl` CLI subcommand (unlike Flow's `uip maestro flow hitl add`).
+
+Full reference: **[references/hitl-casetask-action.md](references/hitl-casetask-action.md)** — three task JSON shapes (QuickForm, generic, app-based), field reference, assignee handling, post-write verification, and downstream output access.
+
+| Path chosen in Step 3 | What gets written |
+|---|---|
+| QuickForm | A `<TaskLabel>.hitl.json` schema file (unified `fields[]` with `direction`, `outcomes[]`) + action task in `caseplan.json` with `data.context[hitlType].value: "quick"`, `_schemaFileId` (placeholder UUID), and `hitlSchemaId` (matches `schemaId` in `.hitl.json`). `data.inputs[]` and `data.outputs[]` are empty arrays. No `root.data.uipath.bindings[]` entries. Apply Step 4b schema-design checks before writing. |
+| App-based | Action task with `data.actionCatalogName`, `data.name` and `data.folderPath` as `=bindings.<id>` references. Add 2 root-level bindings. |
+
+After writing, validate (build-time check — must pass before reporting success):
+
+```bash
+uip maestro case validate <caseplan.json> --output json
+```
+
+> `uip maestro case validate` is the only `uip maestro case` CLI used by this skill on the Case surface. All authoring is direct JSON.
+
+---
+
 ### Surface: Low-Code Agent
 
 The Low-Code Agent escalation CLI (`uip agent escalation add`) is currently in-flight. Until it ships, configure manually:
@@ -296,7 +356,44 @@ response = interrupt(CreateTask(
 
 ### Surface: Maestro
 
-QuickForm and coded-action-app HITL nodes are both supported on Maestro BPMN processes — `uipath.human-in-the-loop.quick-form` and `uipath.human-in-the-loop.coded-action-app` are registered element types in the BPMN validator ([bpmn-spec.json](../uipath-maestro-bpmn/validator/bpmn-spec.json)), same node-type strings as the Flow surface. Write the node directly into the `.bpmn` XML as a `bpmn:UserTask` with a `uipath:activity` extension element (see the `Actions.HITL` extension type in the validator spec for the app-based/coded-action-app XML shape and context fields — `appId`, `appVersion`, `actions`, `key`, `taskTitle`).
+QuickForm and coded-action-app HITL nodes are both supported on Maestro BPMN processes. `uipath.human-in-the-loop.quick-form` and `uipath.human-in-the-loop.coded-action-app` are registered as **registry shortcut names** in the BPMN validator ([bpmn-spec.json](../uipath-maestro-bpmn/validator/bpmn-spec.json)) — these are palette/discovery identifiers, not literal XML to write. There is no dedicated CLI subcommand for Maestro (unlike Flow's `uip maestro flow hitl add`) — write the node directly into the `.bpmn` XML.
+
+**Confirmed node shape (verified by direct reproduction against a real Studio Web BPMN process with a working, editable QuickForm task):**
+
+```xml
+<bpmn:task id="Activity_InvoiceApproval" name="Invoice Approval">
+  <bpmn:extensionElements>
+    <uipath:activity version="v1">
+      <uipath:type value="Actions.HITL" version="v2" />
+      <uipath:context>
+        <uipath:input name="hitlType" type="string" value="quick" />
+        <uipath:input name="taskTitle" type="string" value="Please review this invoice and approve or reject" />
+        <uipath:input name="labels" type="string" />
+        <uipath:input name="priority" type="string" value="Medium" />
+        <uipath:input name="actionCatalogName" type="string" />
+        <uipath:input name="enableActionableNotifications" type="boolean" value="false" />
+        <uipath:input name="assignmentCriteria" type="string" />
+        <uipath:input name="recipient" type="json" />
+        <uipath:input name="_schemaFileId" type="string" value="<see file-id callout below>" />
+        <uipath:input name="hitlSchemaId" type="string" value="<matches schemaId in the .hitl.json sidecar>" />
+        <uipath:inputSchema type="jsonSchema"><![CDATA[{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"invoiceid":{"type":"string","title":"Invoice ID"},"amount":{"type":"number","title":"Amount"}},"required":[]}]]></uipath:inputSchema>
+      </uipath:context>
+      <uipath:input name="HitlTaskArguments" type="json" target="bodyField"><![CDATA[{"invoiceid":"INV-1001","amount":500}]]></uipath:input>
+      <uipath:output name="Action" type="string" source="=Action" var="invoiceDecision" options="[{&#34;value&#34;:&#34;Approve&#34;,&#34;label&#34;:&#34;Approve&#34;},{&#34;value&#34;:&#34;Reject&#34;,&#34;label&#34;:&#34;Reject&#34;}]" />
+    </uipath:activity>
+  </bpmn:extensionElements>
+  <bpmn:incoming>edge_into_task</bpmn:incoming>
+  <bpmn:outgoing>edge_out_of_task</bpmn:outgoing>
+</bpmn:task>
+```
+
+Notes on what's easy to get wrong:
+- **Element is `bpmn:task`, not `bpmn:UserTask`.** `bpmn-spec.json`'s generic `Actions.HITL` XML template uses `bpmn:UserTask` and `version="v1"` — that template is for the app-based/coded-action-app path (its `context` fields are `appId`, `appVersion`, `actions`, `key`, `taskTitle`). A real QuickForm task exported from Studio Web is a plain `bpmn:task` with `uipath:type value="Actions.HITL" version="v2"`. Use the shape above for QuickForm; the spec's template for app-based.
+- **`<uipath:inputSchema>` (last child of `<uipath:context>`) and `<uipath:input name="HitlTaskArguments">` (sibling of `<uipath:context>`, not inside it) are both required.** Without them the "Edit Schema" canvas in Studio Web doesn't open at all — confirmed by direct reproduction. This mirrors the Case surface's `data.inputSchema`/`data.inputs[]` requirement — see [hitl-casetask-action.md § Step 3](references/hitl-casetask-action.md) for the parallel Case shape and full field-by-field rationale.
+- **The `Action` output requires a matching process-level variable declaration** — add `<uipath:inputOutput id="<varId>" name="Action" type="string" elementId="<taskId>" />` inside the process's top-level `<uipath:variables version="v1">` block.
+- **A separate `<TaskLabel>.hitl.json` sidecar file is required**, same shape as the Case surface's (`title`, `fields[]` with `direction`/optional `colSpan`/`binding` or `variable`, `outcomes[]` with **no** `action` key, `schemaId`) — see [hitl-casetask-action.md § Step 2](references/hitl-casetask-action.md) for the exact shape; it's identical across both surfaces.
+- **`_schemaFileId` cannot be authored blind — it is a server-assigned foreign key, not a UUID you invent.** A placeholder value makes "Edit Schema" fail silently (a `404` on Studio Web's internal `FileOperations/File/Rename` call, confirmed by direct reproduction). There is no `uip` CLI command that resolves this today. The only known working procedure: upload once, look up the real file ID Studio Web assigned to the `.hitl.json` via `GET /api/Project/{projectId}/FileOperations/Structure` (an internal Studio Web REST endpoint, not a CLI verb), patch `_schemaFileId` to that real ID, then push the corrected `.bpmn` back with a **targeted single-file update** (`PUT /api/Project/{projectId}/FileOperations/File/{fileId}`) — **not** another whole-project `uip solution upload`, which re-pushes every file and mints a fresh random file ID for each one, invalidating whatever was just patched. This is a real product/tooling gap, not just a documentation gap — flag it to the user rather than silently attempting it, unless they've explicitly asked for the schema to be Studio-Web-editable.
+- **Diagram-interchange edges are required for the connector lines to render, even though the logical `bpmn:sequenceFlow`s already exist.** Every `bpmn:sequenceFlow` needs a matching `bpmndi:BPMNEdge` (with two `di:waypoint` points, aligned to the source/target shapes' connecting edges) in the `bpmndi:BPMNPlane` — omitting it leaves the nodes logically connected but visually disconnected in the canvas. Confirmed by direct reproduction.
 
 Design the schema per Step 4b, confirm it with the user, then validate frequently (`uip maestro bpmn validate <file>.bpmn --output json`) while wiring the node so any shape mistakes surface immediately rather than at deploy time. In Maestro, field names in `outputs`/`inOuts` must exactly match declared process variable names and types.
 
@@ -326,3 +423,4 @@ After completing the wiring:
 - **[How to scaffold a new Coded Action App](references/hitl-node-coded-action-app.md)** — Read this when the user wants to build a new React app inside the solution. Covers full project template, UUID generation, solution CLI commands, and post-creation build steps.
 - **[HITL business pattern recognition](references/hitl-patterns.md)** — Read this during Step 2 / Step 2b to identify whether a process needs a human checkpoint and which pattern applies. Includes proactive recommendation language and when NOT to recommend HITL.
 - **[Action Center URL patterns](../uipath-tasks/references/action-center-urls.md)** (in `uipath-tasks` skill) — Read this before surfacing any Action Center task URL to the user. Covers the missing-tenant-slug anti-pattern and the API-host vs UI-host mapping.
+- **[Case Action Task (HITL)](references/hitl-casetask-action.md)** — Case surface: action task JSON, QuickForm vs app-based paths, `.hitl` file format, context entries, field binding, and downstream output access.

package/skills/uipath-human-in-the-loop/references/hitl-casetask-action.md

@@ -0,0 +1,413 @@
+# HITL Case Action Task — Implementation Reference
+
+The agent writes an `action` task into a stage of `caseplan.json`. **Direct JSON write is the primary method on the Case surface.** Unlike the Flow surface (`uip maestro flow hitl add`), the `uipath-maestro-case` skill ships no single `hitl add` CLI subcommand for the HITL-specific parts (`context[]` entries, `.hitl.json` linkage) — edit `caseplan.json` directly per the path-specific JSON shapes below.
+
+> If the stage or case predates required entry/exit/completion rules (see the checklist below), `uip maestro case` does have CLI mutation commands for those (`stage-entry-conditions`, `stage-exit-conditions`, `case-exit-conditions`, `task-entry-conditions` — each with an `add` subcommand). Prefer them over hand-writing that JSON when the case project already exists as a file you can pass to the CLI. If you're editing a caseplan.json given to you directly (not one you scaffolded yourself with these commands), it's simplest to just include the correct rule shapes directly per the examples below.
+
+Two paths exist. **Present both to the user and confirm before writing:**
+
+| Path | When to use | Requires |
+|---|---|---|
+| **QuickForm** | Structured form fields, no deployed app needed | A separate `.hitl.json` schema file written alongside `caseplan.json` |
+| **App-based action task** | Existing deployed Action Center app with a custom form | `task-type-id` from registry + `tasks describe` |
+
+> **If the user is unsure or says "just pick one":** Default to QuickForm. Say: "I'll use QuickForm — it's the quickest to set up and works for most approval and review tasks. You can always upgrade to a deployed Action Center app later."
+
+> **Build time vs design time.** A case action task lives in two surfaces:
+> - **Design time** — the JSON written into `caseplan.json` (what this skill produces). Studio Web's case designer round-trips this JSON; the QuickForm schema must be valid here.
+> - **Build / runtime time** — `uip maestro case validate` accepts it, `uip solution upload` packs it, and Action Center renders the form to the assignee at runtime.
+>
+> Every shape documented below is required to round-trip in both. After writing, always run `uip maestro case validate <caseplan.json> --output json`.
+
+---
+
+## Step 1 — Extract the Task Configuration Through Conversation
+
+Ask these questions before designing any path. Ask all missing ones in a single message.
+
+| What you need to know | Question to ask |
+|---|---|
+| What the reviewer sees | "What information does the reviewer need to make their decision?" |
+| What they decide or fill in | "Does the reviewer just approve/reject, or do they need to enter data?" |
+| Who receives the task | "Who should receive this task — a specific user (email) or a group?" |
+| Priority | "What priority should this task have? Low, Medium, or High?" |
+
+**Common business descriptions → path selection:**
+
+| Description | Path |
+|---|---|
+| "Reviewer approves invoice; sees ID + amount, clicks Approve/Reject" | QuickForm — `inputs[]` (read-only) + `outcomes[]` |
+| "Human fills in missing vendor name and cost center, then submits" | QuickForm — `outputs[]` (writable) |
+| "Reviewer edits an AI-drafted email, then sends or discards" | QuickForm — `inOuts[]` for the body |
+| "Finance team approves expense claims before payment" | QuickForm — group assignee, outcomes are Approve/Reject |
+| "Manager approves a leave request" | QuickForm — user email assignee, outcomes are Approve/Reject |
+| "Legal reviews and signs off on a contract with custom fields" | App-based — deployed app with custom form layout |
+| "Agent fills in form that a human corrects before submitting" | App-based — outputs populate downstream task inputs |
+
+---
+
+## Path 1 — QuickForm (file-based schema, no deployed app)
+
+The form schema lives in a separate `.hitl.json` file that sits alongside `caseplan.json` in the case project directory. Action Center renders the fields at runtime from the schema — no deployed app required.
+
+> **What makes Path 1 (QuickForm) unique — checklist before you finish:**
+> - ✅ A `<TaskLabel>.hitl.json` file is **created** alongside `caseplan.json`
+> - ✅ `data.context[hitlType].value` is `"quick"` (not `"custom"`)
+> - ✅ `data.context[_schemaFileId].value` is a **plain UUID v4 string** — e.g. `"f1e2d3c4-b5a6-7890-abcd-ef1234567890"`. Never an `=bindings.xxx` expression.
+> - ✅ `data.context[hitlSchemaId].value` is a **plain UUID v4 string** matching `schemaId` in the `.hitl.json` file. Never an `=bindings.xxx` expression.
+> - ✅ `data.inputs[]` and `data.outputs[]` are **empty arrays** (`[]`)
+> - ❌ `data.name` and `data.folderPath` do NOT exist — those are App-based (Path 2) only
+> - ❌ No `=bindings.xxx` expressions anywhere in the task JSON — those are App-based only
+> - ❌ No top-level `bindings[]` entries added
+
+### Step 1 — Design the Schema
+
+Use these roles to plan the fields before writing:
+
+| Role | `field.direction` | Human can… | Use for |
+|---|---|---|---|
+| Input field | `"input"` | Read only | Context the human needs to make a decision |
+| Output field | `"output"` | Write | Data the automation needs back |
+| InOut field | `"inOut"` | Read + modify | Data the human can see and optionally correct |
+
+**Supported field types:** `string`, `number`, `boolean`, `date`, `datetime` (canonical — see [hitl-node-quickform.md](hitl-node-quickform.md) for the same vocabulary on the Flow surface; legacy aliases like `text`/`dateTime` are silently normalized by the runtime, but write the canonical form directly)
+
+**Design rules:**
+- Input fields: bind to upstream case variables via `=vars.<varId>` — never hardcode literals from runtime data
+- Output fields: only what downstream tasks actually consume; set `required: true` for mandatory outputs
+- `outcomes[]`: use domain-specific names (Approve/Reject, not just Submit)
+- Keep it focused — don't add fields the case won't use
+
+**Show the designed schema to the user and confirm before writing.**
+
+### Step 2 — Write the `.hitl.json` File
+
+Generate two UUID v4 values:
+- `schemaId` — identity of the schema, stored inside the file and referenced from the action task
+- `fileId` — placeholder file system ID (Studio Web assigns the real one when it processes the project; use a fresh UUID v4 as a stable placeholder)
+
+Create a file named `<TaskLabel>.hitl.json` in the case project directory (alongside `caseplan.json`).
+
+The file uses a **unified `fields[]` array** — every field has a `direction` property that determines its role. This is the format the sync runtime reads (`parsed?.fields`).
+
+```json
+{
+  "title": "Invoice Approval",
+  "fields": [
+    {
+      "id": "invoiceid",
+      "label": "Invoice ID",
+      "type": "string",
+      "direction": "input",
+      "colSpan": 6,
+      "binding": "=vars.invoiceIdVar"
+    },
+    {
+      "id": "amount",
+      "label": "Amount",
+      "type": "number",
+      "direction": "input",
+      "colSpan": 6,
+      "binding": "=vars.amountVar"
+    },
+    {
+      "id": "notes",
+      "label": "Notes",
+      "type": "string",
+      "direction": "output",
+      "colSpan": 6,
+      "variable": "vars.notes"
+    },
+    {
+      "id": "decision",
+      "label": "Decision",
+      "type": "string",
+      "direction": "output",
+      "colSpan": 6,
+      "variable": "vars.decision"
+    }
+  ],
+  "outcomes": [
+    { "id": "outcome-0", "name": "Approve", "type": "string", "isPrimary": true },
+    { "id": "outcome-1", "name": "Reject",  "type": "string", "isPrimary": false }
+  ],
+  "schemaId": "a3f7c2d1-8b4e-4f9a-b2c5-6d8e1f3a7b9c"
+}
+```
+
+**Field shape reference:**
+
+| Property | Required | Notes |
+|---|---|---|
+| `id` | Yes | lowercase label, strip spaces and non-alphanumeric characters (no separator). `"Invoice ID"` → `"invoiceid"`, `"Due Date"` → `"duedate"` |
+| `label` | Yes | Display label in the form. Validator rejects empty. |
+| `type` | Yes | `string`, `number`, `boolean`, `date`, `datetime` |
+| `direction` | Yes | `"input"`, `"output"`, or `"inOut"` |
+| `colSpan` | No | Grid width hint for the form layout (e.g. `6` of 12). Safe to omit — confirmed optional against a real Studio Web export. |
+| `binding` | For `direction: "input"` / `"inOut"` | `"=vars.<varId>"` — reads from a case variable. A literal is also valid as an `=`-expression (e.g. `="Acme Corp"`), confirmed against a real export, but prefer a variable binding when the value comes from upstream data. |
+| `variable` | For `direction: "output"` / `"inOut"` | The **full** `"vars.<name>"` reference (no leading `=`) the output writes to — not a bare name. Downstream tasks read it as `=vars.<name>`. |
+| `required` | No | `true` for mandatory outputs — omit if false |
+
+**`outcomes[]` shape:** `{ "id": "<slug>", "name": "<OutcomeName>", "type": "string", "isPrimary": <bool> }` — first entry is the primary action. **No `action` key** — confirmed against a real Studio Web export; an earlier draft of this doc invented one, do not reintroduce it.
+
+> **`title` is required, top-level in the `.hitl.json` file** — the form's display title in Action Center, separate from both the task's `displayName` (canvas label) and `data.taskTitle` (the assignee-facing message). All three are independent strings and do not need to match.
+
+### Step 3 — Write the Action Task in `caseplan.json`
+
+```json
+{
+  "id": "ta1b2c3d4",
+  "elementId": "Stage_aB3kL9-ta1b2c3d4",
+  "type": "action",
+  "displayName": "Invoice Approval",
+  "isRequired": true,
+  "shouldRunOnlyOnce": false,
+  "entryConditions": [
+    {
+      "id": "Condition_EnTk1",
+      "displayName": "Entry Rule 1",
+      "rules": [ [ { "id": "Rule_EnTk1", "rule": "current-stage-entered" } ] ]
+    }
+  ],
+  "data": {
+    "taskTitle": "Please review this invoice and approve or reject",
+    "context": [
+      { "name": "hitlType",                    "type": "string",  "value": "quick" },
+      { "name": "taskTitle",                   "type": "string",  "value": "Please review this invoice and approve or reject" },
+      { "name": "labels",                      "type": "string" },
+      { "name": "priority",                    "type": "string",  "value": "Medium" },
+      { "name": "actionCatalogName",           "type": "string" },
+      { "name": "enableActionableNotifications","type": "boolean", "value": "false" },
+      { "name": "assignmentCriteria",          "type": "string",  "value": "user" },
+      { "name": "recipient",                   "type": "json",    "body": { "Type": 2, "Value": "approver@company.com" } },
+      { "name": "_schemaFileId",               "type": "string",  "value": "f1e2d3c4-b5a6-7890-abcd-ef1234567890" },
+      { "name": "hitlSchemaId",                "type": "string",  "value": "a3f7c2d1-8b4e-4f9a-b2c5-6d8e1f3a7b9c" }
+    ],
+    "inputs": [
+      { "name": "invoiceid", "type": "string", "displayName": "Invoice ID", "target": "bodyField", "value": "=vars.invoiceIdVar" },
+      { "name": "amount",    "type": "number", "displayName": "Amount",    "target": "bodyField", "value": "=vars.amountVar" }
+    ],
+    "outputs": [
+      { "name": "Action", "type": "string", "displayName": "Action", "source": "=Action", "var": "invoiceDecision",
+        "options": [ { "value": "Approve", "label": "Approve" }, { "value": "Reject", "label": "Reject" } ] }
+    ],
+    "inputSchema": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "object",
+      "properties": {
+        "invoiceid": { "type": "string", "title": "Invoice ID" },
+        "amount": { "type": "number", "title": "Amount" }
+      },
+      "required": []
+    }
+  }
+}
+```
+
+> **`displayName`, `inputs[]`/`outputs[]`, and `inputSchema` are all required — this is the part an earlier draft of this doc got wrong.** It previously claimed `data.inputs[]`/`data.outputs[]` "are always empty arrays for QuickForm — the schema is in the `.hitl.json` file." That is false. Confirmed against a real Studio Web export and by direct reproduction: without `inputSchema` (a JSON-Schema mirror of the input fields) and populated `inputs[]`/`outputs[]` on the task node itself, Studio Web's "Edit Schema" canvas does not open at all — clicking it does nothing, silently. The `.hitl.json` file and the task's own `data.*` fields are **two parallel representations of the same schema** that must both be written; neither one alone is sufficient.
+> - `inputs[]`: one entry per input field, `name` = field `id`, `value` = the same `=`-expression as that field's `binding` in `.hitl.json`.
+> - `outputs[]`: one entry per **output field with a `variable`**, plus one always-present `Action` entry whose `options[]` mirrors `outcomes[]` from `.hitl.json` (`{value, label}` pairs) — this is the decision/outcome the reviewer picks, not a separate field.
+> - `inputSchema`: a `draft-07` JSON Schema, `properties` keyed by the same field ids as `inputs[]`, each `{"type": "<field type>", "title": "<field label>"}`.
+
+**Context entry notes:**
+
+| `name` | Notes |
+|---|---|
+| `hitlType` | Always `"quick"` for QuickForm |
+| `_schemaFileId` | **Not a value you can invent — see the callout below.** It must be the real, backend-assigned file ID of the uploaded `.hitl.json`, not a fresh UUID. |
+| `hitlSchemaId` | Must match the `schemaId` value inside the `.hitl.json` file exactly. |
+| `taskTitle` | Appears both as `data.taskTitle` (top-level) and in `context[]` — **both are required**. |
+| `labels` | No `value` — leave the entry present but empty. |
+| `priority` | `"Low"` \| `"Medium"` (default) \| `"High"` \| `"Critical"` |
+| `actionCatalogName` | No `value` for QuickForm — leave the entry present but empty. |
+| `enableActionableNotifications` | Leave as `"false"` unless the user explicitly wants email notifications. |
+| `assignmentCriteria` | `"user"` when assigning to a specific email. Omit the `value` (or omit the entry) for group rules. |
+| `recipient` | `{ "Type": 2, "Value": "<email>" }` for email; `{ "Type": 1, "Value": "<group>" }` for group; `{ "Type": 3, "Value": "=vars.<varId>" }` for runtime-resolved assignee. |
+
+> **`_schemaFileId` cannot be authored blind — it is a server-assigned foreign key, not a UUID you invent.** Confirmed by direct reproduction against Studio Web: a placeholder UUID here makes "Edit Schema" fail with a `404` on `FileOperations/File/Rename` (the fileId in that failed request is whatever placeholder was written) — Studio Web does **not** silently reconcile it on upload, contrary to what an earlier draft of this doc claimed. There is currently no `uip` CLI command that resolves this. The only known working procedure:
+> 1. Upload the project once with any placeholder value in `_schemaFileId` (`uip solution upload`).
+> 2. Look up the real ID Studio Web assigned to the `.hitl.json` file via `GET /api/Project/{projectId}/FileOperations/Structure` (find the entry whose `name` matches the `.hitl.json` filename — an internal Studio Web REST endpoint, not a `uip` CLI verb).
+> 3. Patch `_schemaFileId` in `caseplan.json` to that real ID.
+> 4. Push the corrected `caseplan.json` back with a **targeted single-file update** — `PUT /api/Project/{projectId}/FileOperations/File/{fileId}` (same file's own real ID) — **not** another whole-project `uip solution upload`. A second whole-project upload re-pushes every file and mints a **new** random file ID for each one, including `.hitl.json`, immediately invalidating whatever you just patched.
+>
+> This is a real gap, not just a documentation gap: today there is no supported CLI path to make a freshly-authored QuickForm task's schema editable in Studio Web without dropping to this undocumented internal API. Flag this to the user rather than silently attempting it, unless they've explicitly asked for the schema to be Studio-Web-editable.
+
+### Step 4 — Discover Upstream Variables
+
+Read available case variables from the top-level `variables` field in `caseplan.json` (current schema is flat — no `root` wrapper; see [case-schema.md](../../uipath-maestro-case/references/case-schema.md#top-level-shape) in the case skill):
+
+```json
+{
+  "inputs":      [ { "id": "<varId>", "name": "invoiceId", "type": "string" } ],
+  "outputs":     [],
+  "inputOutputs":[]
+}
+```
+
+For cross-task references, source values come from upstream task `outputs[].var` — see [bindings-and-expressions.md](../../uipath-maestro-case/references/bindings-and-expressions.md) in the case skill for the full discovery procedure.
+
+> **No root-level bindings needed for QuickForm.** Unlike App-based (Path 2), QuickForm does **not** add entries to the top-level `bindings[]` array.
+
+### Post-Write Verification (QuickForm)
+
+Run `uip maestro case validate <caseplan.json> --output json`. Confirm:
+
+- `.hitl.json` file exists in the project directory with `schemaId`, `fields[]` (unified array with `direction`), `outcomes[]`
+- Action task `type === "action"`
+- `data.taskTitle` non-empty and matches `data.context[taskTitle].value`
+- `data.context[]` has entries for: `hitlType` (`"quick"`), `_schemaFileId`, `hitlSchemaId`, `taskTitle`, `labels`, `priority`, `actionCatalogName`, `enableActionableNotifications`
+- `data.context[hitlSchemaId].value` matches `schemaId` in the `.hitl.json` file
+- `data.inputs[]`/`data.outputs[]` are populated (mirroring `.hitl.json`'s fields) and `data.inputSchema` is present — see the callout in Step 3
+- top-level `bindings[]` is **not** modified by this path
+
+### Downstream Output Access (QuickForm)
+
+Each field in `outputs[]` and `inOuts[]` exposes its value downstream via the field's `variable` property — the **full** `"vars.<name>"` string, not a bare name:
+
+```json
+{ "id": "decision", "variable": "vars.decision", "type": "string", "label": "Decision" }
+```
+
+Downstream task input value: `"=vars.decision"`. The selected outcome is available via the task's `Action` output (see Step 3).
+
+For the full cross-task wiring procedure, see [bindings-and-expressions.md](../../uipath-maestro-case/references/bindings-and-expressions.md).
+
+---
+
+## Path 2 — App-Based Action Task (deployed Action Center app)
+
+The task form is defined by a deployed Action Center app. Inputs are shown to the human; outputs are collected from the form and usable downstream via `=vars.<var>` expressions.
+
+### Step 1 — Discover the App
+
+```bash
+# Pull the registry first (requires uip login)
+uip maestro case registry pull
+
+# Search for action apps
+uip maestro case registry search --type action-apps --output json
+
+# Get a specific app by name (check action-apps-index.json if CLI search fails)
+uip maestro case registry get "<app-name>" --type action-apps --output json
+```
+
+> CLI search is known to fail for action-apps — always fall back to direct inspection of `~/.uipcli/case-resources/action-apps-index.json`. Use `id` (not `entityKey`), `deploymentTitle` (not `name`), and `deploymentFolder.fullyQualifiedName` for the folder path.
+
+### Step 2 — Get the Input/Output Schema
+
+```bash
+uip maestro case tasks describe --type action --id "<action-app-id>" --output json
+```
+
+Returns `inputs[]` and `outputs[]`. Capture both — they define what the human fills in and what the automation reads back.
+
+### Step 3 — Write Root-Level Bindings
+
+Add 2 entries to the top-level `bindings[]` array — one for `name` and one for `folderPath`. Deduplicate by `(default + resource + resourceKey)`.
+
+```json
+{
+  "id": "bG0SraLpg",
+  "name": "name",
+  "type": "string",
+  "resource": "app",
+  "resourceKey": "Shared.Contract Review App",
+  "propertyAttribute": "name",
+  "default": "Contract Review App"
+},
+{
+  "id": "bH1iJK2lm",
+  "name": "folderPath",
+  "type": "string",
+  "resource": "app",
+  "resourceKey": "Shared.Contract Review App",
+  "propertyAttribute": "folderPath",
+  "default": "Shared"
+}
+```
+
+`resourceKey` = `<folderPath>.<deploymentTitle>`. Binding IDs: `b` + 8 chars.
+
+For the full binding procedure, see [bindings/impl-json.md](../../uipath-maestro-case/references/plugins/variables/bindings/impl-json.md) in the case skill.
+
+### Step 4 — Write the Task
+
+```json
+{
+  "id": "ta1b2c3d4",
+  "elementId": "Stage_aB3kL9-ta1b2c3d4",
+  "type": "action",
+  "isRequired": true,
+  "shouldRunOnlyOnce": false,
+  "entryConditions": [
+    {
+      "id": "Condition_EnTk1",
+      "displayName": "Entry Rule 1",
+      "rules": [ [ { "id": "Rule_EnTk1", "rule": "current-stage-entered" } ] ]
+    }
+  ],
+  "data": {
+    "taskTitle": "Please review this contract and fill in the required fields",
+    "name": "=bindings.bG0SraLpg",
+    "folderPath": "=bindings.bH1iJK2lm",
+    "actionCatalogName": "Contract Review App",
+    "assignmentCriteria": "user",
+    "recipient": { "Type": 2, "Value": "reviewer@company.com" },
+    "context": [
+      { "name": "hitlType", "type": "string", "value": "custom" }
+    ],
+    "inputs": [],
+    "outputs": []
+  }
+}
+```
+
+`data.name` and `data.folderPath` MUST be `=bindings.<id>` references — never string literals.
+`data.inputs[]` and `data.outputs[]` are populated from the `tasks describe` response in Step 2.
+
+> **`hitlType` is `"custom"` for app-based tasks.** App-based tasks have no schema file at all — the form is defined by the deployed app itself, not by a schema document. **Never write `_schemaFileId` or `hitlSchemaId` for an app-based task** — those two context entries exist only on the QuickForm path (Path 1), where they identify the `.hitl.json` schema file. An app-based task is fully described by `data.name`/`data.folderPath` (the bindings to the deployed app) plus `data.inputs[]`/`data.outputs[]` (from `tasks describe`) — nothing else identifies its "schema."
+
+For the full `inputs[]`/`outputs[]` variable shapes, see [action/impl-json.md](../../uipath-maestro-case/references/plugins/tasks/action/impl-json.md).
+
+---
+
+## Post-Write Verification (all paths)
+
+```bash
+uip maestro case validate <caseplan.json> --output json
+```
+
+| Path | Verify |
+|---|---|
+| QuickForm | `.hitl.json` file present with `title`, `fields[]`, `outcomes[]` (no `action` key), `schemaId`; task has `displayName`; `data.context[]` has `hitlType: "quick"`, `_schemaFileId`, `hitlSchemaId` (matches `.hitl.json` `schemaId`), `taskTitle`; `data.inputs[]`/`data.outputs[]` populated (not empty) and `data.inputSchema` present, mirroring `.hitl.json`'s fields; no `actionCatalogName` value; no top-level `bindings[]` entries added |
+| App-based | `type: "action"`, `data.taskTitle` non-empty, `data.name` and `data.folderPath` start with `=bindings.`, `data.context[]` has `hitlType: "custom"` and **no** `_schemaFileId`/`hitlSchemaId` entries (app-based tasks have no schema file), top-level `bindings[]` has 2 entries with `resource: "app"` and `propertyAttribute` = `name` / `folderPath`, `data.actionCatalogName` matches the deployed `deploymentTitle` |
+| Both | The task node has `entryConditions[]` set — e.g. `current-stage-entered` (see the Step 3/4 examples above). Without it, validate fails with `Task has no entry rules`. This is a case-structural requirement, not HITL-specific — it applies to every action task written via direct JSON. |
+
+If validate reports errors, **never report success**. Diagnose from the JSON output and fix before reporting back. A validate error unrelated to the HITL task itself (e.g. `Case has no completion rules` on a stage/case that predates your edit) is a pre-existing gap in the case plan, not something this skill introduces — surface it to the user rather than reverse-engineering the CLI to silence it.
+
+---
+
+## Downstream Output Access
+
+| Path | Outputs available downstream? | How |
+|---|---|---|
+| QuickForm | Yes — every `outputs[]` and `inOuts[]` field in the `.hitl.json` | `field.variable` is already the full `=vars.<name>` reference (minus the leading `=`) |
+| App-based | Yes — every `data.outputs[]` entry | `=vars.<output.var>` |
+
+**QuickForm example:**
+
+```json
+{ "id": "decision", "variable": "vars.decision", "type": "string", "label": "Decision" }
+```
+
+Downstream task input: `"value": "=vars.decision"`.
+
+**App-based example:**
+
+```json
+{ "name": "decision", "type": "string", "id": "out_decision", "var": "decisionVar" }
+```
+
+Downstream task input: `"value": "=vars.decisionVar"`.
+
+For the full cross-task wiring procedure, see [bindings-and-expressions.md](../../uipath-maestro-case/references/bindings-and-expressions.md).