Uipath Maestro Bpmn

Reasoning budget

• Match reasoning to step difficulty and bias toward acting; for mechanical / IO / format steps, if a provided script already covers the task, run it — don't re-derive it.
• Save deep, extended reasoning for the one genuinely hard judgment a script can't make for you.

Working style

• Understand first, then decide. Read this skill's SKILL.md and understand the scripts it ships before you act. Then plan accordingly, such as run a script as-is when it fits, change a script when it's close, or write extra scripts to complement — based on what the scripts actually do, not a guess.
• Plan the whole path up front, then chain. Outline the full sequence of steps before running anything, batch independent steps into one turn, and pipeline the whole plan in as few turns as possible. Don't do things that can be pipelined into one call turn-by-turn.
• Inspect an input ONCE. To learn a file's structure (sheets/columns, pages, form fields, keys), dump it once — ideally to a file you then grep — never re-open the same file field-by-field or retry it with several libraries. A source image is the exception: look at it again whenever it is no longer visible in your context (see Authoring from an image).
• Don't repeat work. Do not rerun a command when its inputs and relevant state are unchanged, and do not reread an unchanged file, script, or SKILL.md already in context. After a tool or command may modify a file, reread the affected content before relying on it.
• Write code once and reuse. If a step needs code, write it once as a small script (paths/params as CLI args) and call it; don't paste near-duplicate inline python across turns. Keep it terse — no comment banners or narration in inline scripts.
• Keep outputs small. Don't put large tool results and outputs into the context, instead write them into a file and use tools to inspect them. If there is no tool available, you should write your own scripts to inspect the file. To decide whether a row exists, filter CLI JSON by field (jq select), never truncate it (head, sed -n).
• Don't do anything unnecessary. Don't call tools, read files, or put results into context unless they're immediately needed.

UiPath Maestro BPMN

Work with UiPath Maestro (Process Orchestration) .bpmn projects across their lifecycle: author, validate, package, operate, and diagnose. Authoring is registry-driven for registered nodes: their execution payloads come from templates the registry serves. The structural BPMN and serializer-owned scaffold metadata that hold those nodes together (process scaffold, variables, bindings, entry points, sequence flows, gateways, events, boundary events, containers, multi-instance markers, and the diagram) are authored from the documented spec and canvas contract. Packaging, operating (upload, publish, run, manage), and diagnosing are driven through the UiPath CLI, covered in the capability references below.

When to use

• Create a Maestro .bpmn from a description, or from an image of a process (sketch, whiteboard or sticky-note photo, screenshot of another diagram).
• Edit .bpmn structure: gateways, events, boundary events, subprocesses, call activities, multi-instance loops, sequence-flow conditions, variables.
• Add a UiPath extension node (RPA job, agent, HITL, queue, business rule, API workflow, Integration Service connector, internal message, timer).
• Validate a .bpmn against the canvas rules before import.
• Package, upload, publish, or run a project, and manage its jobs and instances.
• Diagnose a failed or misbehaving run.

Editing an existing .bpmn (preserve what you did not author)

The skill can edit an existing file. If the edit introduces one of the shapes in Patterns, use that guide — inserting a pattern into a running process is a normal edit, not a reason to skip the shape. Make surgical edits and preserve content you did not author: unknown uipath:* elements, uipath:migrationVersion, tags, imported Integration Service payloads, and stable element IDs. Do not regenerate the whole file or drop extension data the skill does not recognize — preserve-only structures (see the blocklist in references/structural-bpmn.md) round-trip untouched. Never normalize existing nodes to this skill's canonical templates: do not add missing attributes (e.g. type="json" target="bodyField" on an existing uipath:input) to elements the edit does not target — on untouched neighbors only wiring (bpmn:incoming/bpmn:outgoing) may change.

For an existing ScriptTask, preserve its mapping discriminator and uipath:scriptVersion, and do not normalize a working brownfield node merely because the new-node authoring contract differs. Migration requires explicit confirmation — see references/structural-bpmn.md.

For .flow JSON use uipath-maestro-flow; for XAML/coded workflows use uipath-rpa; for Python agents use uipath-agents; for Case plans use uipath-maestro-case.

The model

Two halves make a valid Maestro .bpmn:

1. Registry-listed node payloads — registry-owned. Each listed node's execution XML (uipath:activity / uipath:event / uipath:mapping, its context, input, output, and bindingInfo) comes from uip maestro bpmn registry get <type>'s xmlTemplate. Never hand-author a registry-owned node payload from prose.
2. Structural BPMN and scaffold metadata — spec/canvas-owned. The registry emits no <bpmn:definitions>/<bpmn:process>, no sequence flows, no gateway conditions/defaults, no event-definition payloads, no boundary-event attributes, no subprocess/loop structure, and no diagram. Serializer-owned scaffold extensions such as uipath:variables, uipath:bindings, uipath:entryPointId, and uipath:migrationVersion also come from this contract rather than a node template. Author these from references/structural-bpmn.md, which is grounded in the registry spec, the CLI scaffold, and the canvas serializer.

Patterns

Seven recurring process shapes, for building a new process and for extending one that already runs. Each guide gives a worked-out topology — nodes, wiring, gateway conditions, variables — and the reasoning behind it. Many topologies pass validation for the same request; these are known-good shapes, not specifications. Adapt them: add steps, drop branches, and change counts as the process needs. Each guide's "Why it works" names the parts that carry the shape — change those and you are building something else, so say so. Read the guide for each pattern the process actually uses — one for a simple process, several for a composed one — and none for a pattern you are not building.

Every guide's shape table marks each node Entry (omit when inserting into a process that already runs), Mechanism (changing it changes the pattern), or Placeholder (bind it, or skip it if the process already does this). Author the element the table names. A Placeholder whose target step 1 did not resolve is that element with its registry payload and the identity slots left as public placeholders, never a bare bpmn:task standing in for the work.

Do not reach for a pattern when the ask is a short linear process, a single node, or a change that does not introduce one of these shapes. A pattern is never a wrapper to retrofit onto work that does not need one.

Using more than one pattern in one process? Read references/patterns/composing-guide.md first — which pattern keeps its start event, the four ways the rest join it, how variables cross a nesting boundary, and the two placements the engine constrains. A single pattern needs only its own guide.

Authoring from an image

When the process comes from an image, the job is transcription: every item in the image becomes a node and every visible connector becomes a flow. A plausible process "inspired by" the image is not a transcription. The usual failure is dropping and merging items while summarizing, then building from the summary.

1. Inventory before you interpret. Before proposing any topology, write down every visible item: its exact wording, its colour/shape, and its rough position. Then list every visible connector as source → target, with its label and whether it is certain or ambiguous. Mark unreadable or crossed-out items instead of guessing or skipping them. Keep this list in a notes file outside the project folder.
2. Confirm the inventory, not a summary. The structure you confirm under Rule 4 must list every node and flow from the inventory. Never offer a condensed or "interpreted" topology as the recommended option. Ask a separate question for each ambiguity, and for anything you would add that the image does not show (start/end events, merge gateways the canvas requires, a reading of an implied link).
3. Transcribe 1:1. One node per item, keeping the image's wording and its Yes/No branch labels. Add technical scaffolding only where the canvas requires it, and name each addition in your final report.
4. Keep the image in view. Earlier-turn images may leave your context: hosts can replace them with a text placeholder, especially after the user sends a new message. Before any fidelity work, including when the user says the result does not match, check that you can actually see the image. If you cannot, re-read it from its file path (the attachment path the host provided). If that also fails, ask the user to re-attach it. Never rebuild from memory of the image, from your earlier summary, or from a sub-agent's text description. If a sub-agent transcribed the image, check its result against the image yourself before editing.
5. Verify fidelity before finishing. After validate passes, look at the image again and compare it with the BPMN node by node and flow by flow. Report any remaining mismatch rather than calling the result done. Validation proves the file is structurally valid, not that it matches the image.

Workflow

Work the six steps quickly, but keep the path matched to the user's ask. Treat requests to discover before authoring, save raw registry JSON/evidence, or "do not author yet" as discovery-only even if they describe an eventual BPMN. In that mode, immediately create registry-evidence/, run and save registry pull --output json, registry list --output json or registry search ... --output json, and registry get <type> --output json for each requested type; do not read deep authoring references or scaffold a project. For authoring asks, author early: do not pre-read every reference before writing. Read a reference only when you reach the structure it covers, and read only the section covering it — references/structural-bpmn.md opens with a section index naming every anchor. Get the needed templates, then write the first complete draft before further spelunking.

For registry-evidence-only tasks, follow the command-first recipe in references/registry-workflow.md.

1. Discover. uip maestro bpmn registry pull once (cached for the session — do not re-pull), then list / search to map intent to extension types; uip is connections list --all-folders for live connections (always --all-folders — a folder-scoped list silently misses connections). Never fabricate an identifier; ask only under Rule 4, otherwise decide. Bind each connector node to an Enabled connection for its connector: the one in the folder the task names, else IsDefault Yes, else the first. Confirm it with uip is connections ping <id> --output json (Data.Status must be Enabled; the list's State is cached) and fall to the next candidate when it is not. Another owner is no reason to skip it; name each bound connection's Name, Owner, and Folder (never its Id) as a Rule 4 assumption. Use placeholders only when the user asked for a draft, a handoff, or placeholder, synthetic, public-safe, or sanitized values, or when no candidate pings Enabled. See references/registry-workflow.md.
2. Get templates. uip maestro bpmn registry get <type> --output json for each chosen registry-owned node only. Fetch every chosen template in one Bash call, not one command per turn — each shell round-trip is a model turn and dozens of them exhaust the run's time budget before authoring finishes: for t in TypeA TypeB TypeC; do uip maestro bpmn registry get "$t" --output json; done. Enrich Intsvc.* connector nodes with --connection-id/--object-name; take --object-name from the table in references/registry-workflow.md — a connector exposes several objects per operation and describe does not rank them. Do not call registry get for structural gaps the registry never owns: sequence flows, gateways, events, boundary events, multi-instance/loop markers, errorMapping/retry structure, or diagrams. On every bpmn: tag you paste, opening and closing, lowercase the first letter after bpmn:: <bpmn:UserTask> → <bpmn:userTask>, <bpmn:ServiceTask> → <bpmn:serviceTask>. Preserve the uipath:* payload exactly. BPMN.ScriptTask is the registry lookup key, but a new node serializes <uipath:type value="BPMN.Variables" version="v1" /> — never the lookup key. Local validation accepts the older discriminator, so a clean validate does not prove that mapping is right. For the compatibility fallback and its scope, see references/structural-bpmn.md#script-tasks--jint-authoring-contract.
3. Assemble. Author directly from the complete minimal file in references/structural-bpmn.md plus each node's xmlTemplate (fill placeholders only). That skeleton shows a stable manual entry point, one structural task, and complete DI. Do not reverse-engineer authoring patterns from task fixtures, generated package files, or any installed package bundle under node_modules — such spelunking is the top reason authoring runs out of time. Add only the structural pieces your process needs (extra gateways, events, boundary events, containers, multi-instance markers, expression/error mappings, retry attributes). Leave the diagram to step 4; do not hand-author bpmndi:* while the source is still moving. For a new local project, initialize the supported scaffold with uip maestro bpmn init <ProjectName> --output json, edit at the returned Data.Path, and preserve its generated metadata. For a source-only draft the user has not asked to package or operate, pass --skip-solution-registration so no *Solution/ wrapper or .uipx is created. init takes a project name, not a path, and writes under the current directory: ./<ProjectName>/ with that flag or inside an existing solution, ./<ProjectName>Solution/<ProjectName>/ otherwise.

<!--skill-flavor:named-solution-init:start-->

When the user names a solution ("a solution of the same name" is <ProjectName>, not <ProjectName>Solution), create it and run init from inside it:

uip solution init <SolutionName> --output json
cd <SolutionName> && uip maestro bpmn init <ProjectName> --output json

A Data.AutoCreatedSolution in the response means init ran outside the solution: re-run it from inside and report the stray directory.

<!--skill-flavor:named-solution-init:end-->

To land a project at a path the user named, mkdir -p its parent and run init there with the leaf as the name — and either pass --skip-solution-registration or make that parent a solution first, because default init inserts a <ProjectName>Solution/ level the requested path does not have. Check Data.Path against the requested path before editing. The init scaffold declares no xsi namespace: add xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" to bpmn:definitions before writing any xsi:type attribute. See references/shared/local-metadata-regeneration-guide.md. The runnable BPMN/start-event path belongs in lowercase operate.json.main, never project.uiproj.main. When adding draft or preserve-only case-management variants, include a real lowercase <uipath:caseManagement version="v1">...</uipath:caseManagement> payload with synthetic content as a separate preserve-only extension. Do not treat an Orchestrator.StartCaseMgmtProcess* typed activity shell as a substitute for that payload when the user asks to preserve case-management contract variants. When asked to preserve a generic unsupported uipath:Activity, write the actual capitalized element <uipath:Activity version="v1">...</uipath:Activity>. Do not write <uipath:activity><uipath:type value="uipath:Activity" ... />; that is a lowercase typed shell, not the preserve-only generic payload. When writing public-safe placeholders into XML attribute values, XML-escape angle brackets: use <TENANT_URL>, <FOLDER_KEY>, and <CONNECTION_NAME> in attributes. Raw <PLACEHOLDER> text is only safe in element text or CDATA; unescaped angle brackets inside attributes make the BPMN not well-formed. When routing on an Actions.HITL user task's outcome, the sequence-flow conditions from the exclusive gateway must reference the exact variable bound by the HITL template's <uipath:output ... var="..."> (for example =vars.Var_HitlResult == "approve"), not only a copied or derived script variable. For an Intsvc.* activity whose inputTarget is body (Intsvc.ActivityExecution and its async, agent, and workflow variants), these rules override the template's InputNotes, DiscoveryNotes, and ContextFieldNotes:

• One body. Exactly one <uipath:input name="body" type="json" target="body"> holding the whole request object in CDATA, never one input per field and never a bare array. Dotted names nest (fields.project.key → {"fields":{"project":{"key":…}}}); users[*] is an array under users ({"users":["U1","U2"]}). See Body shape.
• Required Parameters. Each Required: true entry (Slack send_as) is its own uipath:input with target set to its Type, after </uipath:context>, valued from the request, else its DefaultValue. See Parameters.
• operation (Intsvc.ActivityExecution only) is the described Operation.Name (Create, List, Retrieve, Update, Delete, Replace), never the activity's Name.
• Data Service files use UploadFileToRecordField, DownloadFileFromRecordField, and DeleteFileFromRecordField, never the V2 objects uip is resources list shows. See Picking the object.
• folderKey (Intsvc.ActivityExecution only). Keep the template's folderKey context input as =bindings.<folderBindingId> plus its folder binding on every node that binds a connection. Without it the run faults 102010 Value cannot be null (Parameter 'Folder'). See Bindings.
• Values. A Reference field takes the looked-up id (Rule 2). A body value without a leading = is a literal: write "=vars.<id>", and make text mixed with variables one =js: expression ("=js:'Severity: ' + vars.Var_Severity"). For an Integration Service draft or boundary handoff the user asked for (a request that only says to validate is not one), emit only the .bpmn plus the notes file — do NOT create the four generated package files (Rule 16); authoring them fails the boundary the task tests. The node itself is still authored: paste the registry's Intsvc.* template and keep the shell that template declares — uipath:activity for activities, uipath:event for Intsvc.WaitForEvent and Intsvc.EventTrigger (Rule 6) — plus its context and output, filling the resource identity slots with the escaped public placeholders. Event context references the connection as connectionId, activities as connection. A host element carrying neither shell, such as a bare bpmn:sendTask with no uipath:activity, is a missing node, not a draft. Only the resolved values are CLI-owned — see references/registry-workflow.md. For Integration Service draft notes, name every CLI-owned blocker literally, including the exact phrase connection binding, plus dynamic schemas, generated outputs, bindings_v2.json, and package metadata. Avoid softer wording such as "connection and process binding" because it hides the concrete artifact the CLI must supply. Run uip maestro bpmn refresh <project-path> after any edit that changes a start event id or adds or removes an entry point — not only when packaging or operating. Lay the diagram out first (step 4): refresh validates before it writes, so a node you just added fails it with MISSING_DI_SHAPE. operate.json and entry-points.json are generated once and do not follow source edits, so step 5's validator fails on the mismatch: entry-points.json references start event "Event_start" via filePath, but no <bpmn:startEvent id="Event_start"> exists. Authoring from the skeleton above renames the initializer's Event_start, so a source-only draft needs this too. Keep the output as written — that shape is the contract pack consumes. refresh requires an init-generated project: with no project.uiproj it fails Required file is missing / RetryWillNotFix. For a bare .bpmn (the shape of this repo's edit fixtures), write the two-key project.uiproj first — { "Name": "<ProjectName>", "ProjectType": "ProcessOrchestration" } — then refresh, which writes the rest. Only fall back to the equivalent hand-authored shape in references/shared/local-metadata-regeneration-guide.md when the CLI is unavailable. Do not copy CLI scaffold metadata shapes into a synthetic local project. Every root manual start event needs a <uipath:entryPointId value="<uuid>" /> child in its extensionElements; without one refresh fails the whole project RetryWillNotFix instead of writing an empty entry-point list. A connector or timer start is not manual, so a project that runs refresh or pack keeps the initializer's manual start alongside it; only a source-only draft replaces it. Clearing the resulting stale-entry error by editing or deleting entry-points.json instead of running refresh passes validate and pack while shipping an empty bindings_v2.json. Give public inputs and outputs explicit runtime bridges, and converge routes returning one result on a single completion EndEvent — for the two-layer contract see references/structural-bpmn.md.

4. Lay out the diagram. After the last source edit, and before any validate, refresh, or pack — including the refresh step 3 calls for:

   uip maestro bpmn format <file.bpmn>

   It overwrites the file's bpmndi:BPMNDiagram in place, so the canvas renders the process arranged instead of stacked at the origin. Every deliverable gets this, source-only drafts included. It is also a hard precondition for the next two steps, not a cosmetic pass: a node with no BPMNShape or a flow with no BPMNEdge fails validate with MISSING_DI_SHAPE / MISSING_DI_EDGE, no diagram at all fails it with BPMN_PARSE_ERROR, and refresh validates before it writes, so it fails the same way. Edit the source again and the layout is stale — re-run this step before re-validating. If format reports unknown command, update the CLI (see references/cli-conventions.md); if upgrading is unavailable, hand-author the fallback DI structure in references/structural-bpmn.md.

5. Validate. Check well-formedness first. validate tokenizes with a tolerant parser and reports Valid on XML with an unbound namespace prefix, so a ParseError here is a source defect to fix before anything else. Then run the CLI validator, which runs the full PO.Frontend canvas rule set (structural rules plus variable, method-call, input-type, and event-object checks) offline, plus deploy-readiness checks:

   python3 -c "import sys, xml.etree.ElementTree as ET; ET.parse(sys.argv[1])" <file.bpmn> &&
     ! grep -nE '</?bpmn:[A-Z]' <file.bpmn> &&
     uip maestro bpmn validate <file.bpmn> --output json

   validate ignores tag case; a line the grep prints is a tag to lowercase (step 2).

   Exit 0 = valid. Exit 1 = a parse error, a grep hit, or a validate failure. Read severity from each issue's [error]/[warning] tag, not from the Found N error(s) header, which counts errors while the list under it prints warnings too. Fix only error-severity findings, then re-run step 4 and validate again; stop re-validating once every remaining finding is a warning or the placeholder pair below. read but never assigned is a defect no error covers: nothing writes a value the process reads, so a step that should produce it does not. MISSING_RESOURCE (warning) and MISSING_BINDING (error) are one finding about one unresolved node, and the binding half is a live tenant lookup. Bind the node to a deployed resource. When the user asked for a placeholder, draft, or boundary handoff, or step 1 found no Enabled candidate, no invented identifier can clear MISSING_BINDING (Rule 2): exit 1 / RetryWillNotFix is the expected result. Report the pair once and continue; refresh (step 6) succeeds with it unresolved. Fix every VARIABLE_DOES_NOT_EXIST warning: it names a reference with no declaration. A VARIABLE_NOT_SET warning on the node reading a start-event-scoped caller input is expected; see references/structural-bpmn.md#validation.

   [warning] [(xml)] unknown attribute <type> is expected noise from the script-task template's <uipath:inputSchema type="jsonSchema">. Leave it. type is required on uipath:input, uipath:output, and uipath:inputOutput; removing it there fails the load with BPMN_PARSE_ERROR ... to be a string. Do not bisect the file and do not read package bundles under node_modules to find the rule.

   Validation is structural preflight, not runtime proof — see references/cli-conventions.md. When execution is authorized, inspect runtime variables, element executions, and incidents before reporting behavioral success.

   If validate reports "unknown command" or clearly skips the structural rules, the installed CLI predates them — update it (see references/cli-conventions.md). See references/structural-bpmn.md#validation.

6. Refresh derived metadata. Once step 5 leaves no fixable error, regenerate the four CLI-owned package files:

   uip maestro bpmn refresh <project-path> --output json

   Treat a nonzero result as a source/precondition failure: fix the BPMN or project.uiproj, re-run steps 4 and 5, and refresh again — never repair the generated JSON by hand. Refresh after binding a connection (step 1) and for a package-ready, upload, debug, publish, or deploy deliverable; a source-only draft needs it only for step 3's start-event edits. For the full contract (scope, idempotency, binding rules) see references/shared/local-metadata-regeneration-guide.md.