uip maestro bpmn

Commands for authoring, packing, debugging, and operating UiPath Maestro BPMN process-orchestration projects using the `uip maestro bpmn` tool.

uip maestro bpmn authors, packs, debugs, and operates UiPath Maestro projects — BPMN 2.0 business-process orchestrations with long-running, human-in-the-loop semantics. Maestro is one of three sibling orchestration surfaces: BPMN (this page), Flow (uip maestro flow), and Case Management (uip maestro case). Pick BPMN for standard BPMN semantics (user tasks, boundary events, timers, sub-processes), Flow for a node-and-edge graph of agentic or connector-heavy steps, and Case Management for a long-running, human-driven unit of work modeled as stages/tasks/SLAs rather than a linear process.

The tool is shipped as the @uipath/maestro-tool plugin. Every command on this page is registered under the bpmn branch — the real invocation is always uip maestro bpmn <verb>, never a bare uip maestro <verb>. See Tools (plugins) for the plugin model.

Authoring flow

A Maestro project is a directory with a project.uiproj, a .bpmn file, and supporting metadata files (operate.json, entry-points.json, bindings_v2.json, package-descriptor.json).

# 1. Scaffold
uip maestro bpmn init invoice-orchestration

# 2. Edit the .bpmn in Studio Web or your IDE
#    (BPMN is validated at init time via bpmn-moddle)

# 3. Smoke-test via Studio Web
uip maestro bpmn debug ./invoice-orchestration

# 4. Validate the .bpmn file before packing
uip maestro bpmn validate ./invoice-orchestration/invoice-orchestration.bpmn

# 5. Pack for deployment
uip maestro bpmn pack ./invoice-orchestration ./dist --version 1.0.0

# ...or pack + publish straight to Orchestrator in one step
uip maestro bpmn process publish ./invoice-orchestration --folder-key <key>

Authoring commands

Command	Purpose
uip maestro bpmn init	Scaffold a new Maestro project (BPMN starter)
uip maestro bpmn debug	Upload to Studio Web and run a debug session
uip maestro bpmn validate	Validate a project's BPMN and metadata without packing
uip maestro bpmn format	Auto-format and tidy a .bpmn file
uip maestro bpmn refresh	Regenerate generated project files from the current .bpmn
uip maestro bpmn update-metadata	(Deprecated — use refresh) Update generated metadata files
uip maestro bpmn pack	Produce a deployable .nupkg
uip maestro bpmn process publish	Pack and publish to Orchestrator in one step

Runtime

At runtime a published Maestro package becomes a process of type ProcessOrchestration on Orchestrator. Starting one creates an instance; each execution attempt is a job; failures surface as incidents.

Command	Purpose
uip maestro bpmn process	List and run deployed Maestro processes (list, get, run, publish)
uip maestro bpmn processes	Process summaries across folders, per-process incidents, and diagnostics (list, incidents, diagnose, error-codes)
uip maestro bpmn instance	Inspect and steer running instances (list, get, pause, resume, cancel, retry, migrate, goto, variables, message send, element cancel/retry, …)
uip maestro bpmn debug-instance	Debug a specific running instance interactively
uip maestro bpmn incident	Read incident summaries and details
uip maestro bpmn job	Stream traces (traces) and inspect job status

Orchestrator-level jobs and processes are manipulated through the Orchestrator tool — see Orchestrator jobs and Orchestrator processes.

Registry (BPMN)

Maestro also ships a BPMN registry — uip maestro bpmn registry — for browsing the extension types, connectors, and processes usable inside a .bpmn. It is not yet in the sidebar but is callable today:

uip maestro bpmn registry pull   [-f, --force]
uip maestro bpmn registry list   [-l, --limit <n>]
uip maestro bpmn registry search <keyword>
uip maestro bpmn registry get    <extensionType> [--connection-id <id>] [--object-name <name>] [--operation <name>]

Data shapes: RegistryPullSuccess (counts: ExtensionTypeCount, ConnectorCount, ProcessCount), RegistryListSuccess / RegistrySearchSuccess (Data.ExtensionTypes[], Data.Connectors[], Data.Processes[]), RegistryGetSuccess (Data.ExtensionType, optional Data.ISEnrichment when both --connection-id and --object-name are provided).

Conventions

• Every uip maestro bpmn subcommand honors the global options (--output, --output-filter, --log-level, --log-file).
• Default output is JSON.
• Exit codes follow the standard contract.
• Most runtime commands require uip login first — see Authentication.

See also

• uip maestro flow — graph-shaped workflow sibling
• uip maestro case — Case Management sibling
• Tools (plugins)
• Authentication
• Global options, Exit codes