From 5dcd08149b04495f60161ddd8e1b5191de56b2fd Mon Sep 17 00:00:00 2001
From: Dushyant Pathak <dushyant.pathak@uipath.com>
Date: Fri, 8 May 2026 00:10:24 +0530
Subject: [PATCH] fix(hitl): document node.outputs block with per-field custom
 outputs

Add outputs block to the Full Node JSON example showing:
- base output and status entries
- per-field custom: true entries for schema output/inOut fields
  (source: =result.<fieldId>, var: <variable>)

Also update variables.nodes example to include per-field binding entries,
add note explaining when to add per-field globals, and extend the Runtime
Variables table with $vars.<nodeId>.<variable> and $vars.<variable> rows.

Aligns with CLI fix in uipcli#1894 which made addHitlNode() set node.outputs
with per-field outputs. flow-core uses node.outputs to expose $vars paths on
the canvas; missing outputs caused custom output variables to be invisible.
---
 .../references/hitl-node-quickform.md         | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/skills/uipath-human-in-the-loop/references/hitl-node-quickform.md b/skills/uipath-human-in-the-loop/references/hitl-node-quickform.md
index a1c9fdcc..9298e647 100644
--- a/skills/uipath-human-in-the-loop/references/hitl-node-quickform.md
+++ b/skills/uipath-human-in-the-loop/references/hitl-node-quickform.md
@@ -150,6 +150,12 @@ The node schema uses `fields[]` entries inside `inputs.schema`. Use these concep
       ]
     }
   },
+  "outputs": {
+    "output":   { "type": "object", "source": "=result",        "var": "output" },
+    "status":   { "type": "string", "source": "=result.Action", "var": "status" },
+    "notes":    { "type": "string", "source": "=result.notes",    "var": "notes",    "custom": true },
+    "decision": { "type": "string", "source": "=result.decision", "var": "decision", "custom": true }
+  },
   "model": { "type": "bpmn:UserTask", "serviceType": "Actions.HITL" }
 }
 ```
@@ -248,6 +254,16 @@ The HITL node exposes two outputs (`output`, `status`). After adding it, **compl
       "id": "invoiceReview1.status",
       "type": "string",
       "binding": { "nodeId": "invoiceReview1", "outputId": "status" }
+    },
+    {
+      "id": "invoiceReview1.notes",
+      "type": "string",
+      "binding": { "nodeId": "invoiceReview1", "outputId": "notes" }
+    },
+    {
+      "id": "invoiceReview1.decision",
+      "type": "string",
+      "binding": { "nodeId": "invoiceReview1", "outputId": "decision" }
     }
   ]
 }
@@ -255,6 +271,8 @@ The HITL node exposes two outputs (`output`, `status`). After adding it, **compl
 
 Include entries for **all** nodes in the flow, not just the HITL node. Replace the entire array — do not append.
 
+**Per-field outputs:** When the schema has `output` or `inOut` direction fields, add one entry per field using the output key name from `node.outputs` (the `variable` property value, or the camelCase-derived name when `variable` is omitted). These are also materialized as flow-level globals in `variables.globals` with `direction: "out"`.
+
 ---
 
 ## Schema Conversion — Examples
@@ -350,6 +368,8 @@ After the HITL node, downstream nodes can reference:
 | `$vars.<nodeId>.output` | object | All `output` and `inOut` fields the human filled in, keyed by **field `id`** |
 | `$vars.<nodeId>.output.<fieldId>` | varies | Individual field value using the field's `id` property (e.g. `$vars.invoiceReview1.output.decision`) |
 | `$vars.<nodeId>.status` | string | Selected outcome id (e.g. `"approve"`, `"reject"`) |
+| `$vars.<nodeId>.<variable>` | varies | Per-field output also exposed as a named node variable (key matches `field.variable` or the derived camelCase name) |
+| `$vars.<variable>` | varies | Workflow-global variable (`custom: true` in `outputs`). Accessible without the node prefix in downstream expressions |
 
 > **`fieldId` not `variable`**: The output object properties are keyed by the field's `id` (e.g. `"decision"`), not by the `variable` property. The `variable` property creates a separate workflow-global variable (`$vars.{variable}`) — it does not change the key used in the output object. If a field has `"id": "dec1"` and `"variable": "approvalResult"`, access it as `$vars.nodeId.output.dec1`, not `.approvalResult`.