| name | uipath-longrunning-workflow |
| tags | ["uipath-dev","long-running","studio","hitl","persistence","processdiagram"] |
| description | UiPath Studio (desktop) Long Running Automation — ProcessDiagram XAML (upa:ProcessDiagram), Flowchart Builder designer, supportsPersistence, HITL, queues. Mandatory root pattern x:Class="LongRunningWorkflow" on entry XAML; project.json with FlowchartBuilder + Persistence + FormActivityLibrary + FormActivityLibrary.Contracts; missing-activity troubleshooting; uipathcli analyze. For Maestro or web BPMN use uipath-bpmn-maestro. Triggers on "Long Running Automation", "Main-Queue", "ProcessDiagram", "LongRunningWorkflow", "Flowchart Builder", "blank canvas", "Studio long running workflow", "approval process with persistence", "missing dependencies", "QueueItemData", "unresolved activity". |
UiPath Long Running Workflow (Studio Desktop)
Generate UiPath Studio long-running automations using upa:ProcessDiagram (Long Running Workflow designer / Flowchart Builder activities) with HITL Platform integration for human-in-the-loop processes. This is the Windows Studio project model, not the Maestro web modeler.
Production Reference: This skill is based on the production-validated SALES02_RenewalPriceCommitment project at C:\UiPath\SALES02_RenewalPriceCommitment.
Not this skill
| Use another skill | When |
|---|
uipath-bpmn-maestro | Process modeling in Maestro / Studio Web (bpmn.uipath.com), Maestro docs, BPMN import for cloud process design — not desktop .xaml / project.json codegen. |
uipath-automation | Standard sequences/flowcharts, transactional automations without Long Running Automation / ProcessDiagram as the main entry. |
Official documentation (read-first)
Use these together: Studio explains the designer and project setup; Activities lists every Flowchart Builder activity, properties, and examples.
From the Studio guide (align implementation and explanations with this product wording):
- Designer: Long Running Workflow uses a dedicated canvas; activities appear under Activities → Long Running Workflow (plus Recommended for roots that can be Change Type’d into other elements).
- New file: Ribbon New → Long Running Workflow, or start from Backstage Long Running Automation template (Start tab New from template or Templates tab).
- Dependencies (default for a Long Running Workflow):
UiPath.FlowchartBuilder.Activities (mandatory—do not remove) and UiPath.System.Activities.
- BPMN import: Explorer Import Files →
*.bpmn creates a long running workflow; unsupported BPMN shapes show a warning on the node and validation errors until Change Type fixes them. (This is Studio file import, not Maestro cloud modeling.)
- Manual Trigger is always present by default, can be moved but not deleted; use Change Type to switch it to On a Schedule or On App Trigger where appropriate.
- Process Mining: nodes can be tracked for mining/analytics (see Studio doc).
- Resilience / errors (product terms): Detached Error Handler, Error Boundary Event, Error End Event—map to XAML patterns in this skill (
BoundaryNode, EventSubProcessNode, Throw/Terminate).
- Canvas hygiene: Change color (Default, Green, Blue, Red, Yellow, Violet) for readability; optional for generated XAML but valid in Studio.
Activity categories in the Flowchart Builder docs match how to think about the diagram: Triggers, Sequences (task placeholders), Subprocesses, Gateways, Events (catch/intermediate; Error Handler attaches to Sequence or Subprocess), End. Nested details (Manual Trigger, Sequence → Human Approval, Resume after Delay, etc.) are in the linked activity pages.
QUICK REFERENCE: Dependencies by activity (add to project.json when you add activities)
| Activity / type | NuGet package |
|---|
upa:ProcessDiagram, Flowchart Builder nodes, Subprocess | UiPath.FlowchartBuilder.Activities |
| Log Message, Assign, Sequence, Invoke Workflow File, Add Queue Item (system) | UiPath.System.Activities |
Add Queue Item And Get Reference, Wait For Queue Item And Resume, QueueItemData, Form/App task persistence | UiPath.Persistence.Activities |
Form contracts (transitive dep of Persistence 1.8.x — declare explicitly in project.json) | UiPath.FormActivityLibrary + UiPath.FormActivityLibrary.Contracts (e.g. [2.0.8], same pattern as production LRW projects) |
| HTTP / Integration Service connectors | UiPath.WebAPI.Activities + often UiPath.IntegrationService.Activities (and connector-specific bundles) |
Always apply Dependency hygiene and validation (mandatory) when editing project.json or when Studio shows missing types or activities.
Dependency hygiene and validation (mandatory)
This section is part of the skill contract for generated LRW projects: follow it on every change that touches UiPath.Persistence.Activities, QueueItemData, or Add Queue Item And Get Reference.
1. Persistence and Form packages (do not skip)
UiPath.Persistence.Activities (e.g. 1.8.x) declares a dependency on UiPath.FormActivityLibrary.Contracts. If those packages are only pulled transitively, NuGet may log an “approximate best match” for Contracts in .local/nuget.cache, which correlates with missing or invalid activities and UnknownType on QueueItemData at design time.
Rule: Whenever UiPath.Persistence.Activities is in project.json, also declare explicitly (same pattern as production SALES02):
UiPath.FormActivityLibrary — e.g. "[2.0.8]"UiPath.FormActivityLibrary.Contracts — e.g. "[2.0.8]"
Then Manage Dependencies → Restore (or reopen the project). If problems persist with a stale cache, close Studio, delete the project .local folder once, and reopen.
2. Missing or invalid activities in Studio
Use the product workflow: Missing or Invalid Activities — read Output (red lines name the package), inspect the dependency tree on the project root, Repair invalid dependencies, install missing versions, restore again.
3. CLI governance analyze before handoff / CI
- Install official uipathcli (the
uipath binary that supports studio package analyze). The Python pip install uipath CLI is different and does not implement studio package ….
- Close Studio (or at least close the project) before running
uipath studio package analyze — the analyzer uses Studio’s local DB and fails if the project is open (“already opened in another Studio instance”).
- Cross-check with
uipath-cli-git and UiPath CLI reference (.claude/skills/_shared/ — same path with a Cursor junction to this repo), and with Studio Workflow Analyzer for rule coverage.
QUICK REFERENCE: Critical XAML Rules
Before generating ANY LRW XAML, remember these rules:
Root workflow file (Long Running entry with ProcessDiagram)
Studio binds the Long Running Workflow / Flowchart Builder canvas to the root .xaml declaration. Generated entry workflows must match the Long Running Automation template and production SALES02 (Main-Queue.xaml), not a generic sequence-style root.
| Requirement | Description |
|---|
x:Class="LongRunningWorkflow" on the root <Activity> | Production LRW files use this class name for the top-level workflow. Using the project name as x:Class (e.g. LrwSkillTest) is a common mistake and can cause the wrong designer or a blank / non-rendering Flowchart Builder surface. File name (e.g. Main.xaml) may still differ; class name stays LongRunningWorkflow. |
Default input arguments on the root <Activity> as attributes | e.g. this:LongRunningWorkflow.in_FolderName="Shared" — same pattern as Studio-generated LRW. Prefer this over long this:ClassName.prop / <InArgument><Literal> child blocks under the root (those are easy to get wrong and differ from the template). |
PresentationFramework in TextExpression.ReferencesForImplementation | Included in working LRW projects; supports WPF types used in diagram view state (av:Point, etc.). |
UiPath.Persistence.Activities.Queue in TextExpression.NamespacesForImplementation | Declare alongside UiPath.Persistence.Activities when using QueueItemData / queue persistence activities. |
Validated in Studio: This pattern matches production SALES02 (Main-Queue.xaml: x:Class="LongRunningWorkflow", attribute defaults on <Activity>). An additional end-to-end sample used to confirm the Flowchart Builder surface loads correctly: workspace folder cursor_projects/LrwSkillTest (Main.xaml + project.json + Workflows/PreFlight_Check.xaml). Use it as a structural reference; project name may differ from the root class name.
Minimal root <Activity> shape (first line only — ellipsis indicates xmlns attributes Studio emits):
<Activity mc:Ignorable="sap sap2010" x:Class="LongRunningWorkflow"
this:LongRunningWorkflow.in_FolderName="Shared"
xmlns="http://schemas.microsoft.com/netfx/2009/xaml/activities" xmlns:this="clr-namespace:" … />
After x:Members, follow with sap:VirtualizedContainerService, TextExpression.*, then a single upa:ProcessDiagram (not a top-level Sequence).
| Rule | Description |
|---|
| Inline Nodes | ALL nodes (EventNode, TaskNode, DecisionNode, EndNode) MUST be defined INLINE via nested .Next chains |
| x:Reference Purpose | x:Reference at end of ProcessDiagram only REFERENCES existing inline nodes - does NOT define new nodes |
| Shared EndNode | Define EndNode INLINE in one branch, use <x:Reference> in other branches to point to it |
| Single Next | Each TaskNode can only have ONE <upa:TaskNode.Next> element |
| IdRef Required | Every node MUST have sap2010:WorkflowViewState.IdRef attribute |
| ViewState Required | Every node MUST have sap:WorkflowViewStateService.ViewState with ShapeLocation, ShapeSize, ConnectorLocation |
| Subprocess Structure | Subprocess = TaskNode with NodeType="Task.Subprocess" containing embedded ProcessDiagram |
| Webhook Pattern | ApprovalFlow → Subprocess (webhook wait) → DecisionNode (route based on decision) |
Common Errors:
'Nodes' property has already been set → Nodes defined both inline AND separately (see Pitfall 13b)'Next' property has already been set → TaskNode has two <upa:TaskNode.Next> elementsValue cannot be null → Missing sap2010:WorkflowViewState.IdRef or x:ReferenceErrorActivity → Missing namespace/assembly references for Integration Service connectors- **
InvalidCastException: Literal1[...] to type Argument** → For the **LRW root** workflow, prefer **this:LongRunningWorkflow.argumentName="value"** attributes on (template style). If using child elements, wrap literals in, not a bare underthis:ClassName.propertyName`
- Missing dependency / unresolved activities → Dependency hygiene and validation (mandatory); Studio doc: Missing or Invalid Activities.
Pre-finalize (CI / handoff): See section 3 in Dependency hygiene and validation (mandatory) — uipath studio package analyze via uipathcli, Studio closed, plus Workflow Analyzer.
CRITICAL: Canvas Context Required (MANDATORY)
BEFORE generating ANY long-running workflow code, you MUST:
- Do not generate any XAML until planning is complete. If the user has or references a canvas/solution flow, run
workflow-planning first and obtain workflow-plan.md or equivalent. Greenfield process (no canvas): still produce an execution plan (sequence, gateways, I/O per workflow)—use workflow-planning’s checklist style or a short written plan—before generating Main-Queue.xaml / ProcessDiagram.
┌─────────────────────────────────────────────────────────────────┐
│ MANDATORY WORKFLOW │
│ │
│ 1. FIND CANVAS ──> 2. RUN PLANNING ──> 3. GENERATE CODE │
│ solution-flow.json workflow-planning this skill │
└─────────────────────────────────────────────────────────────────┘
Step 1: Locate Canvas File
**/solution-flow*.json
**/*canvas*.json
**/docs/*.json
Step 2: Extract from Canvas
For EACH approval workflow node, extract:
| Canvas Field | Maps To |
