uipath-human-in-the-loop

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, 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, 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.

When to Use This Skill

• User describes approval gates — invoice approval, offer letter review, compliance sign-off, PO authorization
• User describes exception escalation — "if confidence is low, escalate to a human", fraud alert review
• User describes write-back validation — "human approves before agent writes to ServiceNow / SAP / CRM"
• User describes data enrichment — human fills in missing fields the automation cannot resolve
• User describes agentic output review — "review AI-generated email/RCA/summary before it goes out"
• User describes IT change or access approval — CAB gate, runbook sign-off, access provisioning review
• User describes HR or contract workflow — offer letter review, contract approval, termination sign-off
• User describes financial transaction approval — payment release, price override, expense over limit
• User describes customer communication approval — agent-drafted reply that needs human sign-off before sending
• User explicitly asks to add a HITL node, human review step, or Action Center task
• User is building any automation where a human must act before the process can continue

Do not use this skill for: managing, reassigning, escalating, or monitoring existing Action Center tasks at runtime — use the uipath-tasks skill for those operations. When answering a runtime task management question, provide only administration guidance. Do NOT suggest adding a HITL node, flow, or automation as a follow-up tip or recommendation — even if delays or escalations are mentioned.

See references/hitl-patterns.md for the full business pattern recognition guide.

---

Critical Rules

1. Confirm schema with the user before writing anything for quickform type. Show the designed schema and wait for explicit confirmation. Running non-interactively (CI/headless — no user available to answer): do not block — design the schema from the prompt and any upstream .flow data, write the node, and record the chosen schema prominently in the final report. Only stop and report the open decision if the request is too ambiguous to pick a sensible default. (A prompt that already specifies the fields, outcomes, and output shape is never too ambiguous.)
2. Always wire the completed handle. A HITL node with no outgoing edge on completed blocks the flow forever. Only completed is available as an output handle — not output, success, or any other name. This is true even when inserting into an existing flow whose other nodes use "sourcePort": "output".
3. Always add the definition entry when inserting into an existing flow. Before writing the node, check workflow.definitions[] for the correct nodeType for the selected path ("uipath.human-in-the-loop.quick-form" for QuickForm, "uipath.human-in-the-loop.coded-action-app" for app-based). If absent, append the full definition entry (with handleConfiguration including the completed handle). Skipping the definition means the completed handle is invisible to the runtime and the wiring check fails.
4. Regenerate variables.nodes after adding the node. Replace the entire workflow.variables.nodes array — do not append. See the reference docs for the algorithm.
5. Validate after every change. Run uip maestro flow validate <file> --output json after writing the node and edges. The uip CLI does not accept --format; using it produces error: unknown option '--format' and exit code 3.
6. Read the existing .flow file before adding. Understand which nodes already exist and where the HITL checkpoint belongs in the flow.
7. The definition entry is added once per node type. Check workflow.definitions — if an entry with the matching nodeType is already there, do not add it again.

---

Step 0 — Resolve the uip binary

UIP=$(command -v uip 2>/dev/null || npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip
$UIP --version

Use $UIP in place of uip for all subsequent commands if the plain uip command isn't found.

Local dev note: If working inside the uipcli repo, replace uip with bun run start.

---

Step 1 — Detect the Surface and Find the Flow File

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

# Check for Maestro .bpmn (Maestro process)
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
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

If the user mentioned a specific file path, use that directly.

If no .flow file exists and surface is Flow, scaffold solution-first — Flow projects MUST live inside a solution:

# Probe the solution verb once per session before scaffolding:
#   uip solution init --help --output json
# Success → use `solution init` (post-rename, default).
# `unknown command` → CLI predates the rename; substitute `uip solution new <SolutionName>` below.

uip solution init <SolutionName> --output json
cd <SolutionName> && uip maestro flow init <ProjectName>
# Creates: <SolutionName>/<ProjectName>/<ProjectName>.flow

The flow file path is <SolutionName>/<ProjectName>/<ProjectName>.flow (double-nested). <SolutionName>/ is the solution directory (contains the .uipx file); <ProjectName>/ inside it is the flow project. By convention <SolutionName> and <ProjectName> are often the same string, but they are two distinct scaffolding arguments. Run uip maestro flow init outside a solution and it auto-scaffolds <ProjectName>Solution/<ProjectName>/ for you; running uip solution init first lets you control the solution name (otherwise it defaults to <ProjectName>Solution). Passing --skip-solution-registration leaves a bare single-nested <ProjectName>/<ProjectName>.flow layout that fails Studio Web upload, packaging, and downstream tooling.

---

Step 2 — Read the Business Context

Read the existing .flow file to understand current nodes and edges. Use the Read tool on the .flow file path, then identify:

1. Where the human decision point belongs (after which existing node)
2. What the human needs to see — data produced by upstream nodes
3. What the human must provide back — data needed by downstream nodes
4. What actions they can take — the named outcome buttons
5. Form type: QuickForm (inline schema, node type uipath.human-in-the-loop.quick-form) or AppTask (deployed coded app, node type uipath.human-in-the-loop.coded-action-app)?

---

Step 2b — Proactive HITL Recommendation

If the user did NOT explicitly mention HITL, scan the business description for these signals before proceeding:

Signal	Pattern	Why a human checkpoint matters
"agent writes to", "updates", "posts to" an external system	Write-back validation	Prevents incorrect writes to production systems
"if confidence is low", "when uncertain", "edge case"	Exception escalation	Agent cannot resolve autonomously
"approves", "reviews", "signs off", "four-eyes"	Approval gate	Business or compliance requirement
"fills in missing", "validates extraction", "corrects"	Data enrichment	Automation produced incomplete data
"compliance", "regulatory", "audit trail"	Compliance checkpoint	Mandated human sign-off

When a signal is found, say this before doing anything else:

"I noticed that [quote the specific part of their description]. This is a [pattern name] — a point where [brief consequence if no human reviews]. I recommend inserting a Human-in-the-Loop step here so that [human role] can [action] before the automation [continues/writes/sends]. Should I add it?"

Wait for confirmation. Do not proceed to schema design until the user confirms. Running non-interactively (CI/headless — no user available to answer): treat the recommendation as accepted when the signal is clear-cut (an explicit approval / review / sign-off requirement), add the HITL step, and record that you did so in the final report; only skip it and report the open decision when the signal is ambiguous.

Example:

User: "Build an automation that reads support tickets, uses AI to generate an RCA, and updates the ticket in ServiceNow."

Agent: "I noticed that the automation writes AI-generated content directly back to ServiceNow. This is a write-back validation pattern — if the RCA is incorrect and nobody reviews it, wrong data goes into production tickets. I recommend inserting a Human-in-the-Loop step so that a support lead can review and optionally edit the RCA before the update is applied. Should I add it?"

---

Step 3 — Choose Task Type

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
1	QuickForm	uipath.human-in-the-loop.quick-form	Inline typed form — fields rendered by Action Center from the schema you design here
2	New Coded Action App	uipath.human-in-the-loop.coded-action-app	Scaffold a new React + TypeScript app inside the solution — full UI control
3	Existing Deployed App	uipath.human-in-the-loop.coded-action-app	Reference an app already deployed to Orchestrator

If the user's request is purely business-oriented (no mention of a deployed app, coded action app, or custom UI): skip the question and proceed directly with QuickForm. Do not ask. Say: "I'll use QuickForm — it's inline, no deployment step needed, and works for most approval and review tasks."

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 Coded Action App later."

User selects	Next step
QuickForm	Read How to write a QuickForm HITL node for Steps 1–2, then continue with Step 4
New Coded Action App	Read How to scaffold a new Coded Action App for Step 4c details, then continue with Step 4
Existing Deployed App → ask: "What is the name of the deployed action app?"	Read How to wire an existing deployed Action App for Step 4b details, then continue with Step 4

Fallback rules — what to do when the chosen path hits a blocker:

Path	Blocker	Response
Existing Deployed App	App not found in Orchestrator	"I couldn't find an app with that name. Would you like to try a different name, or fall back to QuickForm while you prepare the app?"
New Coded Action App	No dist/ build present in the source path	"The source folder doesn't have a dist/ build yet. Run your build first (npm run build or equivalent), then come back. Or I can set up a QuickForm now so the flow is wired and ready — you can swap in the app later."
New Coded Action App	User can't provide a source path	"If you don't have the app code ready yet, I'll use QuickForm to wire the HITL checkpoint. You can replace it with a Coded Action App once it's built."
Any custom app	Auth expired (401 on API call)	"The session looks expired — run uip login to refresh your credentials, then retry."

---

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, 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, 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)" | | Priority | "What priority should this task have? Options: Low, Medium, High (default: Low)" |

---

Step 4b — Schema Design Resilience (QuickForm — Flow and Case)

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

Pick direction based on what the human does with the field:

Signal	Direction
"can see", "shown to", "read-only", "displays", "context for reviewer"	input
"fills in", "enters", "types", "selects", "required decision", "approves"	output
"can edit", "can correct", "pre-filled but editable", "suggested value the reviewer can adjust"	inOut

inOut means the field is pre-populated from an upstream node AND the human can modify it before submitting. The runtime exposes it under $vars.<nodeId>.output.<fieldId> the same as an output 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. Case also supports datetime (distinct from date, for full date+time values) — see 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 (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

Every field in inputs.schema.fields must have a non-empty label. flow validate emits HITL_QUICK_FORM_FIELD_LABEL_REQUIRED (error severity) for each field with an empty or whitespace-only label — Debug and Publish are blocked until all labels are filled in. Never generate a field with "label": "" or omit the label key.

---

Step 5 — Write the Node Directly

Surface: Flow — QuickForm (inline schema only)

Write the node JSON directly into workflow.nodes, add the definition to workflow.definitions (once), wire edges into workflow.edges, and regenerate workflow.variables.nodes. Direct JSON is the default.

Node JSON, definition entry, edge format, variables.nodes algorithm, and four worked examples: How to write a QuickForm HITL node

CLI (opt-in): When the user explicitly requests a CLI command:

uip maestro flow hitl add <path/to/file.flow> \
  --label "<TaskLabel>" \
  --priority <Low|Medium|High> \
  --assignee <email-or-group> \
  --schema '<json>' \
  --output json

The CLI writes the node, adds the definition entry, and updates variables.nodes automatically. Wire the completed port after it returns.

After writing, validate:

uip maestro flow validate <file> --output json

Surface: Flow — Coded Action App (new inline)

Step 4c must be completed first — app name confirmed, solution directory located, SDK tarball identified, schema designed and confirmed.

Scaffold the project directory and all source files, add the project to the solution, write the solution resource files, then write the HITL node (type uipath.human-in-the-loop.coded-action-app) with inputs.app referencing the new app (appSystemName: null since the app has not been deployed yet).

Full project template, UUID generation, solution CLI commands, resource file templates, node JSON, and post-creation build steps: How to scaffold a new Coded Action App

After writing, validate:

uip maestro flow validate <file> --output json

Surface: Flow — AppTask (deployed action app only)

Step 4b must be completed first — app resolved, configuration retrieved. Then:

Resolve the solution context (.uipx file), write solution resource files, register the app reference, merge debug_overwrites.json, then write the node JSON (type uipath.human-in-the-loop.coded-action-app) with inputs.app populated from the Step 3b configuration.

App search/selection, retrieve-configuration, resource file writing, complete node JSON with appInputBindings: How to wire an existing deployed Action App

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 — 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):

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:

agent.json escalation entry:

{
  "escalations": [
    {
      "name": "<escalation-name>",
      "inputSchema":  { "inputs": [...], "inOuts": [...] },
      "outputSchema": { "outputs": [...], "outcomes": [...] }
    }
  ]
}

Agent source (Python):

from uipath.sdk import interrupt, CreateTask

response = interrupt(CreateTask(
    escalation_name="<escalation-name>",
    data={ "fieldName": value }
))
# response contains the human's outputs and chosen outcome

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 as registry shortcut names in the 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):

<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 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 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 on Studio Web's internal call, confirmed by direct reproduction). There is no CLI command that resolves this today. The only known working procedure: upload once, look up the real file ID Studio Web assigned to the via (an internal Studio Web REST endpoint, not a CLI verb), patch to that real ID, then push the corrected back with a () — another whole-project , which re-imports everything and mints a fresh random file ID for every file, 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.

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.

---

Step 6 — Report to the User

After completing the wiring:

1. What was inserted — node ID, label, insertion point
2. Schema summary — what the human will see (input-direction fields), fill in (output/inOut-direction fields), and click (outcomes). For deployed action app show the actionSchema from the retrieve-configuration api response here.
3. Edges wired — which handles were connected and to which nodes; any handles left unwired
4. Runtime variables — $vars.<nodeId>.output (object) and $vars.<nodeId>.status (string) and how to reference them downstream
5. Validation result — pass or errors to fix
6. Production readiness note:
   • QuickForm: ready to deploy once the solution is packaged. No additional build steps.
   • New Coded Action App: the app must be built (npm run build inside the app source) and the solution packaged before the HITL task can be used in production. The app will appear with appSystemName: null until first deployment assigns it a system name.
   • Existing Deployed App: ready to deploy immediately — the app is already live.
7. Next step — pack and publish when ready via uipath-development skill

---

References

• How to write a QuickForm HITL node — Read this after the user confirms QuickForm in Step 3. Covers the complete node JSON, definition entry, edge wiring, variables.nodes regeneration algorithm, and four worked schema examples.
• How to wire an existing deployed Action App — Read this when the user selects an existing deployed app in Step 3. Covers app lookup via the Orchestrator API, inputs.app field mapping, appInputBindings, and solution resource files.
• How to scaffold a new Coded Action App — 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 — 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 (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) — Case surface: action task JSON, QuickForm vs app-based paths, .hitl file format, context entries, field binding, and downstream output access.