# 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`](./uip-maestro-flow.md)), and Case Management ([`uip maestro case`](./uip-maestro-case.md)). 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)](./concepts-tools.md) 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`).

```bash
# 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`](./uip-maestro-bpmn-init.md) | Scaffold a new Maestro project (BPMN starter) |
| [`uip maestro bpmn debug`](./uip-maestro-bpmn-debug.md) | Upload to Studio Web and run a debug session |
| [`uip maestro bpmn validate`](./uip-maestro-bpmn-validate.md) | Validate a project's BPMN and metadata without packing |
| [`uip maestro bpmn format`](./uip-maestro-bpmn-format.md) | Auto-format and tidy a `.bpmn` file |
| [`uip maestro bpmn refresh`](./uip-maestro-bpmn-refresh.md) | Regenerate generated project files from the current `.bpmn` |
| [`uip maestro bpmn update-metadata`](./uip-maestro-bpmn-update-metadata.md) | *(Deprecated — use `refresh`)* Update generated metadata files |
| [`uip maestro bpmn pack`](./uip-maestro-bpmn-pack.md) | Produce a deployable `.nupkg` |
| [`uip maestro bpmn process publish`](./uip-maestro-bpmn-process.md#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`](./uip-maestro-bpmn-process.md) | List and run deployed Maestro processes (`list`, `get`, `run`, `publish`) |
| [`uip maestro bpmn processes`](./uip-maestro-bpmn-process.md) | Process summaries across folders, per-process incidents, and diagnostics (`list`, `incidents`, `diagnose`, `error-codes`) |
| [`uip maestro bpmn instance`](./uip-maestro-bpmn-instances.md) | Inspect and steer running instances (`list`, `get`, `pause`, `resume`, `cancel`, `retry`, `migrate`, `goto`, `variables`, `message send`, `element cancel`/`retry`, …) |
| [`uip maestro bpmn debug-instance`](./uip-maestro-bpmn-debug-instances.md) | Debug a specific running instance interactively |
| [`uip maestro bpmn incident`](./uip-maestro-bpmn-incidents.md) | Read incident summaries and details |
| [`uip maestro bpmn job`](./uip-maestro-bpmn-job.md) | Stream traces (`traces`) and inspect job status |

Orchestrator-level jobs and processes are manipulated through the Orchestrator tool — see [Orchestrator jobs](./uip-or-jobs.md) and [Orchestrator processes](./uip-or-processes.md).

### 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](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`).
- Default output is **JSON**.
- Exit codes follow the [standard contract](./exit-codes.md).
- Most runtime commands require `uip login` first — see [Authentication](./authentication.md).

## See also

- [`uip maestro flow`](./uip-maestro-flow.md) — graph-shaped workflow sibling
- [`uip maestro case`](./uip-maestro-case.md) — Case Management sibling
- [Tools (plugins)](./concepts-tools.md)
- [Authentication](./authentication.md)
- [Global options](./global-options.md), [Exit codes](./exit-codes.md)