uipath-longrunning-workflow

# 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](https://bpmn.uipath.com/)), [Maestro docs](https://docs.uipath.com/maestro/automation-cloud/latest), 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. | Doc | URL | |-----|-----| | **Long Running Workflows** (Studio user guide) | [docs.uipath.com/studio/standalone/latest/user-guide/long-running-workflows](https://docs.uipath.com/studio/standalone/latest/user-guide/long-running-workflows) | | **Flowchart Builder Activities** (Workflow Activities pack) | [docs.uipath.com/activities/other/latest/workflow/flowchart-builder-activities](https://docs.uipath.com/activities/other/latest/workflow/flowchart-builder-activities) | | **Missing or Invalid Activities** (Output panel, dependency tree, Repair, Manage Packages) | [docs.uipath.com/studio/standalone/2023.10/user-guide/unresolved-activity](https://docs.uipath.com/studio/standalone/2023.10/user-guide/unresolved-activity) | 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)](#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](https://docs.uipath.com/studio/standalone/2023.10/user-guide/unresolved-activity) — 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](https://github.com/UiPath/uipathcli/releases)** (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](../_shared/uipath-cli.md)** (`.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):** ```xml <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>` elements - `Value cannot be null` → Missing `sap2010:WorkflowViewState.IdRef` or `x:Reference` - `ErrorActivity` → Missing namespace/assembly references for Integration Service connectors - **`InvalidCastException: Literal`1[...] to type Argument`** → For the **LRW root** workflow, prefer **`this:LongRunningWorkflow.argumentName="value"`** attributes on `<Activity>` (template style). If using child elements, wrap literals in `<InArgument><Literal/></InArgument>`, not a bare `<Literal>` under `this:ClassName.propertyName` - **Missing dependency / unresolved activities** → [Dependency hygiene and validation (mandatory)](#dependency-hygiene-and-validation-mandatory); Studio doc: [Missing or Invalid Activities](https://docs.uipath.com/studio/standalone/2023.10/user-guide/unresolved-activity). **Pre-finalize (CI / handoff):** See **section 3** in [Dependency hygiene and validation (mandatory)](#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:** 0. **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 ```bash # Search patterns **/solution-flow*.json **/*canvas*.json **/docs/*.json ``` ### Step 2: Extract from Canvas For EACH approval workflow node, extract: | Canvas Field | Maps To |