# uip maestro bpmn process and uip maestro bpmn processes

> Syntax and options for `uip maestro bpmn process` and `uip maestro bpmn processes`, covering per-folder and tenant-wide published Maestro BPMN process operations.

Once a Maestro BPMN package is published to Orchestrator it becomes a **process** of type `ProcessOrchestration`. Both command groups below are registered under the `bpmn` branch. This page covers two related command groups:

- **`uip maestro bpmn process`** — per-folder operations on a single process definition (list in a folder, get its schema, run it, pack+publish it).
- **`uip maestro bpmn processes`** *(plural)* — tenant-wide summaries, per-process incident lookup, and diagnostics.

## Synopsis

```
# Singular — per-folder, operational
uip maestro bpmn process list    -f <folder-key> [--filter <odata>] [--login-validity <minutes>]
uip maestro bpmn process get     <process-key> <feed-id> -f <folder-key> [--login-validity <minutes>]
uip maestro bpmn process run     <process-key> <folder-key> --release-key <key>
                                  [-i, --inputs <json>] [--feed-id <id>] [--robot-ids <ids>]
                                  [--login-validity <minutes>]
uip maestro bpmn process publish <project-path> [output-path] -f <folder-key>
                                  [-n, --name <name>] [--process-name <name>] [-v, --version <version>]
                                  [-i, --inputs <json>] [--feed-id <id>] [--entry-point <path>]
                                  [--wait [--timeout <seconds>] [--poll-interval <seconds>]] [--login-validity <minutes>]

# Plural — tenant-wide summary, incidents, and diagnostics
uip maestro bpmn processes list       [--folder-key <key>] [-l <limit>] [--offset <n>] [--status <status>]
uip maestro bpmn processes incidents  <process-key> --folder-key <key>
uip maestro bpmn processes diagnose   <process-key> --folder-key <key>
uip maestro bpmn processes error-codes <process-key> --folder-key <key>
```

All subcommands require `uip login` and honor [global options](./global-options.md). Exit codes follow the [standard contract](./exit-codes.md).

---

## uip maestro bpmn process list

List available Maestro processes (releases) in a specific folder.

### Options

| Option | Required | Description |
|---|---|---|
| `-f, --folder-key <key>` | yes | Folder key (GUID). |
| `--filter <odata>` | no | Additional OData filter applied server-side. |
| `--login-validity <minutes>` | no | Token-refresh threshold (default `10`). |

### Data shape (`--output json`)

```json
{
  "Code": "MaestroProcessList",
  "Data": [
    {
      "name":           "InvoiceOrchestration",
      "processKey":     "a1b2c3d4-0000-0000-0000-000000000001",
      "processVersion": "1.0.0",
      "packageId":      "a1b2c3d4-0000-0000-0000-000000000001",
      "packageVersion": "1.0.0",
      "releaseKey":     "e5f6a7b8-0000-0000-0000-000000000001",
      "folderKey":      "c3d4e5f6-0000-0000-0000-000000000001",
      "feedId":         "default",
      "folderId":       42,
      "active":         "Yes",
      "latest":         "Yes"
    }
  ]
}
```

---

## uip maestro bpmn process get

Fetch the entry-point schema (input/output JSON schemas) for a Maestro process.

### Arguments

- `<process-key>` *(required)* — process key.
- `<feed-id>` *(required)* — feed ID (from `list`).

### Options

- `-f, --folder-key <key>` *(required)*
- `--login-validity <minutes>` *(default `10`)*

### Data shape

```json
{
  "Code": "MaestroProcessGet",
  "Data": [
    {
      "Path":         "/content/main.bpmn#Event_start",
      "DisplayName":  "Manual trigger",
      "Type":         "processorchestration",
      "InputSchema":  "{\"type\":\"object\",\"properties\":{}}",
      "OutputSchema": "{\"type\":\"object\",\"properties\":{}}"
    }
  ]
}
```

`InputSchema` and `OutputSchema` are re-stringified JSON Schema strings.

---

## uip maestro bpmn process run

Start a Maestro job for a published process.

### Arguments

- `<process-key>` *(required)* — versioned package process key from `process list`, for example `MyProcess:1.0.0`.
- `<folder-key>` *(required)* — folder key (GUID).

### Options

| Option | Required | Description |
|---|---|---|
| `--release-key <key>` | **yes** | Release key (GUID) — from `process list`. |
| `-i, --inputs <json>` | no | Inputs as a JSON string or `@path/to/file.json`. If omitted and stdin is piped, stdin is parsed. |
| `--feed-id <id>` | no | Feed ID for package lookup (optional). |
| `--robot-ids <ids>` | no | Comma-separated robot IDs (optional). |
| `--login-validity <minutes>` | no | Token-refresh threshold (default `10`). |

There is no `--validate` option on this command — inputs are sent as-is; the process itself is responsible for rejecting bad input.

**Input precedence**: `--inputs <json>` / `--inputs @file.json` > stdin > empty object `{}`.

### Examples

```bash
# Inline JSON
uip maestro bpmn process run "InvoiceOrchestration:1.0.0" "<folder-key>" \
  --release-key <release-key> --inputs '{"amount":100}'

# From a file
uip maestro bpmn process run "InvoiceOrchestration:1.0.0" "<folder-key>" \
  --release-key <release-key> --inputs @inputs.json

# Piped stdin
echo '{"amount":100}' | uip maestro bpmn process run "InvoiceOrchestration:1.0.0" "<folder-key>" --release-key <release-key>
```

### Data shape

```json
{
  "Code": "MaestroJobStarted",
  "Data": {
    "jobKey":  "b2c3d4e5-0000-0000-0000-000000000001",
    "state":   "Pending",
    "traceId": "d4e5f6a7-0000-0000-0000-000000000001"
  }
}
```

Next step: `uip maestro bpmn job traces <jobKey>` to stream execution or `uip maestro bpmn job status <jobKey>` to poll.

---

## uip maestro bpmn process publish

Pack a Maestro BPMN project directory into a `.nupkg` and publish it as an Orchestrator process release, in one step.

### Arguments

- `<project-path>` *(required)* — path to the Maestro BPMN project directory.
- `[output-path]` *(optional)* — output directory for the generated `.nupkg`. Defaults to a temp directory.

### Options

| Option | Description |
|---|---|
| `-f, --folder-key <key>` | **Required.** Folder key (GUID). |
| `-n, --name <name>` | Package name. Default: the project folder name. |
| `--process-name <name>` | Process release name. Default: the package name. |
| `-v, --version <version>` | Package version. Default `1.0.0`. |
| `-i, --inputs <json>` | Default input parameters as a JSON string, `@file.json`, or `-` for stdin. |
| `--feed-id <id>` | Feed ID for package upload (optional). |
| `--entry-point <path>` | Entry point path for the process. |
| `--wait` | Wait until the published package's entry points are available, instead of returning immediately after upload. |
| `--timeout <seconds>` | Maximum seconds to wait for publish propagation when `--wait` is set. Default `300`. |
| `--poll-interval <seconds>` | Seconds between publish propagation checks when `--wait` is set. Default `5`. |
| `--login-validity <minutes>` | Token-refresh threshold. Default `10`. |

### Example

```bash
uip maestro bpmn process publish ./invoice-process \
  --folder-key <folder-key> --version 1.2.0 --wait
```

### Data shape

```json
{
  "Code": "MaestroProcessPublished",
  "Data": {
    "Package": "invoice-process@1.2.0",
    "PackagePath": "/tmp/maestro-process-publish-.../invoice-process.processOrchestration.ProcessOrchestration.1.2.0.nupkg",
    "ProcessKey": "invoice-process.processOrchestration.ProcessOrchestration",
    "ProcessVersion": "1.2.0",
    "ReleaseKey": "e5f6a7b8-0000-0000-0000-000000000001",
    "ReleaseName": "invoice-process",
    "Action": "Created",
    "Upload": [
      { "key": "invoice-process.processOrchestration.ProcessOrchestration", "status": "Created" }
    ],
    "EntryPoints": 1
  }
}
```

`Action` is `"Created"` on first publish of a given process key, `"Updated"` on subsequent publishes.

---

## uip maestro bpmn processes list

Tenant-wide (or folder-scoped) summary of Maestro processes. Unlike the singular `process list`, no `processType` filter is applied server-side — the plural command is shared across tools (Maestro, Flow, Case) and does not scope to `ProcessOrchestration` on its own.

### Options

| Option | Description |
|---|---|
| `--folder-key <key>` | Optional. Scope the summary to one folder. |
| `-l, --limit <number>` | Number of items to return (1-10000). |
| `--offset <number>` | Number of items to skip (0-1000000). Default `0`. |
| `--status <status>` | Filter by process status. |

### Data shape

```json
{
  "Code": "ProcessList",
  "Data": [ /* array of Maestro process summaries */ ]
}
```

:::note
The exact field set of each process summary is specified by the Maestro runtime and may evolve; run the command once with `--output json` against a tenant with data to see the fields you will be consuming, and pin `@uipath/cli` in CI if you parse specific fields.
:::

---

## uip maestro bpmn processes incidents

Get all incidents for a specific Maestro process definition.

### Arguments

- `<process-key>` *(required)* — process definition key.

### Options

- `--folder-key <key>` *(required)*

### Data shape

```json
{
  "Code": "ProcessIncidents",
  "Data": [ /* array of process incidents */ ]
}
```

---

## uip maestro bpmn processes diagnose

Correlate a process's summary, incidents, and error codes in a single call — a convenience wrapper over `processes list`, `processes incidents`, and `processes error-codes`.

### Arguments

- `<process-key>` *(required)* — process definition key.

### Options

- `--folder-key <key>` *(required)*

### Data shape

```json
{
  "Code": "ProcessDiagnostics",
  "Data": {
    "ProcessKey": "InvoiceOrchestration",
    "FolderKey": "c3d4e5f6-0000-0000-0000-000000000001",
    "Summary": { /* the matching process summary object, or null if not found */ },
    "FaultedCount": 2,
    "RunningCount": 5,
    "Incidents": [ /* array of incident objects */ ],
    "IncidentCount": 1,
    "ErrorCodes": [ /* array of error code strings */ ],
    "ErrorCodeCount": 1
  }
}
```

---

## uip maestro bpmn processes error-codes

Get the unique error codes raised by incidents for a specific process.

### Arguments

- `<process-key>` *(required)* — process definition key.

### Options

- `--folder-key <key>` *(required)*

### Data shape

```json
{
  "Code": "ProcessIncidentErrorCodes",
  "Data": [ /* array of error code strings */ ]
}
```

## See also

- [`uip maestro bpmn instances`](./uip-maestro-bpmn-instances.md) — inspect and steer running executions
- [`uip maestro bpmn job`](./uip-maestro-bpmn-job.md) — traces and status for a single job
- [`uip maestro bpmn incidents`](./uip-maestro-bpmn-incidents.md) — incident summaries and details
- [Orchestrator jobs](./uip-or-jobs.md), [Orchestrator processes](./uip-or-processes.md)
- [Maestro overview](./uip-maestro-bpmn.md)