# Maestro BPMN (Preview)

> Maestro BPMN process orchestrations authored from a description, validated against canvas rules, then published, run, and diagnosed with a coding agent.

A Maestro BPMN process orchestrates structured, repeatable business work as an executable Business Process Model and Notation (BPMN) 2.0 diagram — events, tasks, gateways, and sequence flows. With a coding agent, you describe the process, and the agent builds a runnable `.bpmn` project, then helps you validate, publish, run, and diagnose it.

## What you build

A Maestro BPMN process follows steps and branches that are known at design time, even when individual steps, such as agents, reason non-deterministically. It suits work such as invoice processing, where the path is fixed and only the data varies, or application intake, where the approval and rejection branches are all defined up front.

### What a process is built from

- **Events and gateways** — start, end, message, timer, and error events, boundary events attached to tasks, and exclusive, parallel, inclusive, and event-based gateways that route the process.
- **Tasks** — steps that call other UiPath resources and systems: human-in-the-loop tasks, Integration Service connectors, Orchestrator jobs and queues, and script tasks.
- **Subprocesses** — subprocesses that group logic, multi-instance subprocesses that repeat steps, and event subprocesses that handle errors across a whole scope.
- **Variables and expressions** — the variables, bindings, and conditions that carry data between steps and decide which branch a process takes.

## The full lifecycle

| Stage | What your coding agent does | Example prompt |
| --- | --- | --- |
| Author | Builds a `.bpmn` project from your description, or edits a process you already have and leaves the parts it didn't change alone. | *Model an onboarding process as a BPMN orchestration.* |
| Validate | Lays out the diagram and checks it against the canvas rules. This is a structural check and doesn't prove the process runs correctly. | *Validate this process and fix any errors.* |
| Publish | Refreshes the package files and uploads the process to Studio Web, or deploys it to Orchestrator when you ask. | *Upload this process to Studio Web so I can review it on the canvas.* |
| Run | Runs or debugs the process on your approval, and pauses, resumes, cancels, retries, or migrates an instance when you ask. | *Run a debug session for this process with a sample invoice.* |
| Diagnose | Reads job status, incidents, variables, and element executions for a failed run, and maps the failure to the BPMN element that caused it. It changes nothing until you agree to a fix. | *This process instance faulted. Find out which element failed and why.* |

## The skill behind it

This work is powered by the `uipath-maestro-bpmn` skill, which authors, operates, and diagnoses Maestro BPMN projects. Validation runs locally first, and cloud-side actions such as upload, publish, deploy, and run wait for your approval. You can see it in the [Skills catalog](skills-catalog.md). To install it, refer to [Install and set up](install-and-set-up.md).

## A typical starting prompt

A first request might look like this:

"Model an invoice approval process as a Maestro BPMN: receive an invoice, extract its fields, route it to a manager for approval when the amount is over 5,000, and post it to the finance system once approved. Add error handling so a failed posting notifies a supervisor."

The agent builds the process and validates it before it uploads, publishes, or runs anything.

## More prompts to try

- Add an approval step where a manager reviews requests over a set amount, with a reminder if no one responds within a day.
- Add error handling so a failed step notifies a supervisor instead of ending the process silently.
- Edit this existing BPMN to add a parallel branch that notifies the requester while the approval runs.
- Upload this process to Studio Web so I can review it on the canvas.

## Go deeper

For the full picture of Maestro BPMN with a coding agent, refer to [Build a Maestro BPMN with a coding agent](https://docs.uipath.com/maestro/automation-cloud/latest/user-guide/building-maestro-bpmn-with-coding-agents).