# uip maestro case process & job

> Syntax and options for `uip maestro case process`, `processes`, `job`, `instance`, and `incident` — running and inspecting Case Management processes and their executions.

Runtime commands for `uip maestro case`: `process` runs a case process and manages its settings/variable tags, `job` inspects one execution attempt, `instance` inspects/steers the resulting process instance, `processes` gives a cross-process summary view, and `incident` reads incidents. See [Case overview](./uip-maestro-case.md) for concepts shared across the whole `case` subsystem.

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

`instance`, `incident`, and `processes` share their implementation with the equivalent [BPMN](./uip-maestro-bpmn-instances.md) and [Flow](./uip-maestro-flow-instances.md) commands (`@uipath/maestro-sdk`'s shared-commands module) — same defects, same fixes apply, parameterized here for Case (`toolLabel: "Case"`, `processType: "CaseManagement"`). One real behavioral difference: **`instance`'s `--folder-key` is optional here** (`folderKeyRequired: false`), where it's required on the BPMN/Flow equivalents.

## Synopsis

```
uip maestro case process list --folder-key <key> [--filter <odata>] [--login-validity <minutes>]
uip maestro case process get <process-key> <feed-id> --folder-key <key> [--login-validity <minutes>]
uip maestro case process run <process-key> <folder-key> [--inputs <json|@file>] [--release-key <key>] [--feed-id <id>] [--robot-ids <ids>] [--validate] [--login-validity <minutes>]
uip maestro case process settings get <process-key> --folder-key <key>
uip maestro case process settings set <process-key> --folder-key <key> --inputs <json|@file>
uip maestro case process variable-tags get <process-key> --folder-key <key>
uip maestro case process variable-tags set <process-key> --folder-key <key> [--variable <name>]... [--element-id <id>] [--all] [--searchable <true|false>] [--tags <csv>] [--add-tags <csv>] [--remove-tags <csv>] [--inputs <json|@file>]

uip maestro case processes list [--folder-key <key>] [--limit <n>] [--offset <n>] [--status <status>]
uip maestro case processes incidents <process-key> --folder-key <key>
uip maestro case processes diagnose <process-key> --folder-key <key>
uip maestro case processes error-codes <process-key> --folder-key <key>

uip maestro case job traces <job-key> [--folder-key <key>] [--poll-interval <ms>] [--traces-service <name>] [--pretty] [--login-validity <minutes>]
uip maestro case job status <job-key> [--folder-key <key>] [--detailed] [--login-validity <minutes>]

uip maestro case instance list --folder-key <key> [-l <limit>] [--next-page <cursor>] [--process-key <k>] [--package-id <id>] [--error-code <code>] [--status <status>]... [--from-date <iso-8601>] [--to-date <iso-8601>]
uip maestro case instance get <instance-id> [--folder-key <key>]
uip maestro case instance pause|resume|cancel|retry <instance-id> [--folder-key <key>] [--comment <text>]
uip maestro case instance migrate <instance-id> <new-version> [--folder-key <key>] [--comment <text>]
uip maestro case instance incidents|asset|cursors|element-executions|variables|variables-all|global-variables <instance-id> [--folder-key <key>]
uip maestro case instance variables-set <instance-id> [--folder-key <key>] --inputs <json|@file>
uip maestro case instance goto <instance-id> <transitions> [--folder-key <key>]
uip maestro case instance element cancel|retry <instance-id> <element-id> [--folder-key <key>] [--comment <text>]
uip maestro case instance message send [--folder-key <key>] [--inputs <json|@file>]

uip maestro case incident summary [--folder-key <key>] [-l <limit>] [--offset <n>] [--process-key <k>] [--status <status>] [--severity <severity>]
uip maestro case incident get <incident-id> --folder-key <key>
```

## uip maestro case process

Manage Case processes: list what's published to a folder, inspect an entry point's input/output schema, and run one.

:::note
`process run` takes `<folder-key>` as a **positional argument**, not a flag — different from every other verb on this page (`list`/`get`/`settings`/`variable-tags`), which all use `--folder-key`/`-f`. This asymmetry is real, not a typo — verify against your own CLI version's `--help` if a copy-pasted example seems to fail.
:::

### uip maestro case process list

List Case processes published to a folder.

#### Options

| Option | Required | Description |
|---|---|---|
| `-f, --folder-key <key>` | **yes** | Folder key (GUID). |
| `--filter <odata>` | no | Additional OData filter. |
| `--login-validity <minutes>` | no | Minimum minutes before token expiration to trigger a refresh. Default `10`. |

#### Data shape

```json
{
  "Code": "CaseProcessList",
  "Data": [
    {
      "name": "InvoiceReview",
      "processKey": "a1b2c3d4-0000-0000-0000-000000000001: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 case process get

Get a process's entry-point schemas — the input/output shape `process run` expects.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<process-key>` | yes | Process key. |
| `<feed-id>` | yes | Feed ID, from `process list`'s `feedId` field. |

#### Options

| Option | Required | Description |
|---|---|---|
| `-f, --folder-key <key>` | **yes** | Folder key (GUID). |
| `--login-validity <minutes>` | no | Default `10`. |

#### Data shape

```json
{
  "Code": "CaseProcessGet",
  "Data": [
    {
      "Path": "/content/caseplan.json.bpmn#Trigger_1",
      "DisplayName": "Start",
      "Type": "CaseManagement",
      "InputSchema": "{\"type\":\"object\",\"properties\":{}}",
      "OutputSchema": "{\"type\":\"object\",\"properties\":{}}"
    }
  ]
}
```

`Data` is an array — one entry per entry point the process exposes, not a single object. Fails with an explicit error if the process has zero entry points.

### uip maestro case process run

Start a Case process instance.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<process-key>` | yes | Process key. |
| `<folder-key>` | yes | Folder key (GUID) — **positional here**, not a flag. |

#### Options

| Option | Required | Description |
|---|---|---|
| `-i, --inputs <json>` | no | Input parameters as a JSON string or `@file.json`. Omit to read from stdin instead; omit both for empty inputs (`{}`). |
| `--release-key <key>` | no | Release key (GUID), from `process list`. |
| `--feed-id <id>` | no | Feed ID for package lookup. |
| `--robot-ids <ids>` | no | Comma-separated numeric robot IDs. Fails fast if any entry isn't a number. |
| `--validate` | no | Run basic client-side validation (required fields + primitive types) against the process's input schema before submitting. Prints ✅/❌ and exits `1` on failure without starting a job. |
| `--login-validity <minutes>` | no | Default `10`. |

#### Example

```bash
uip maestro case process run a1b2c3d4-0000-0000-0000-000000000001 c3d4e5f6-0000-0000-0000-000000000001 \
  --inputs '{"amount":100}'
```

#### Data shape

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

The success message points you at `uip maestro case job traces <jobKey>` to watch execution.

### uip maestro case process settings

Read or replace a process's raw settings object (the same object `variable-tags` reads/writes one field of).

| Verb | Arguments | Options | Notes |
|---|---|---|---|
| `get` | `<process-key>` | `-f, --folder-key <key>` **required** | `Code: "ProcessSettingsGet"`. |
| `set` | `<process-key>` | `-f, --folder-key <key>` **required**, `--inputs <json\|@file>` | Read-modify-write: GETs current settings, PUTs your payload as the new object. `Code: "ProcessSettingsSet"`. |

### uip maestro case process variable-tags

Tag a process's output variables (for example, marking one searchable for instance-list filtering). Two independent modes — pick one, not both:

- **Friendly mode**: `--variable <name>` (repeatable) + `--element-id`/`--all` to target, plus `--searchable <true|false>` or the lower-level `--tags`/`--add-tags`/`--remove-tags` to mutate.
- **Raw mode**: `--inputs <json|@file>` with the full `variableTags` payload.

| Verb | Arguments | Options | Notes |
|---|---|---|---|
| `get` | `<process-key>` | `-f, --folder-key <key>` **required** | Returns just the `variableTags` object. `Code: "ProcessVariableTagsGet"`. |
| `set` | `<process-key>` | `-f, --folder-key <key>` **required**, plus the friendly/raw flags above | Mixing `--inputs` with any friendly flag is an error. `--element-id` only works with exactly one `--variable`. `--searchable` can't combine with `--tags`/`--add-tags`/`--remove-tags`. `Code: "ProcessVariableTagsSet"`. |

#### Example

```bash
# Mark the "amount" output searchable
uip maestro case process variable-tags set a1b2c3d4-… --folder-key <key> --variable amount --searchable true
```

## uip maestro case processes

Cross-process summary view — list every process's aggregate counts, or drill into one by key. Shares implementation with [BPMN `processes`](./uip-maestro-bpmn-process.md) and Flow's equivalent, filtered to `processType: "CaseManagement"`.

| Verb | Arguments | Options | Notes |
|---|---|---|---|
| `list` | — | `--folder-key <key>`, `-l/--limit <n>`, `--offset <n>`, `--status <status>` | `Code: "ProcessList"`. |
| `incidents` | `<process-key>` | `--folder-key <key>` **required** | `Code: "ProcessIncidents"`. |
| `diagnose` | `<process-key>` | `--folder-key <key>` **required** | Correlates summary + incidents + error codes in one call. `Code: "ProcessDiagnostics"` with `FaultedCount`/`RunningCount`/`IncidentCount`/`ErrorCodeCount` rollups. |
| `error-codes` | `<process-key>` | `--folder-key <key>` **required** | `Code: "ProcessIncidentErrorCodes"`. |

## uip maestro case job

Inspect one execution attempt (a job) of a Case process.

### uip maestro case job traces

Stream execution trace events for a running or recently completed job.

#### Options

| Option | Default | Description |
|---|---|---|
| `--folder-key <key>` | — | Optional — scopes the trace request. |
| `--poll-interval <ms>` | `2000` | Polling interval. |
| `--traces-service <name>` | `llmopstenant_` | Traces service name. |
| `--pretty` | off | Human-readable trace lines instead of raw JSON. |
| `--login-validity <minutes>` | `10` | Token-refresh threshold. |

Traces stream directly to output — no final `Data` payload. Exit code `0` on success, `1` otherwise.

### uip maestro case job status

Get a job's status.

#### Options

| Option | Required | Default | Description |
|---|---|---|---|
| `--folder-key <key>` | no | authenticated folder | Folder key (GUID, from `process list`). **Optional here** — omit to let the backend resolve your default folder. |
| `--detailed` | no | off | Full response instead of the curated summary. |
| `--login-validity <minutes>` | no | `10` | Token-refresh threshold. |

#### Data shape (default summary)

```json
{
  "Code": "CaseJobStatus",
  "Data": {
    "key": "b2c3d4e5-0000-0000-0000-000000000001",
    "state": "Successful",
    "runtimeType": "…",
    "processType": "CaseManagement",
    "startTime": "2025-04-15T10:30:00Z",
    "endTime": "2025-04-15T10:32:11Z",
    "creationTime": "…",
    "inputArguments": "…",
    "outputArguments": "…",
    "info": "…",
    "releaseName": "InvoiceReviewProcess",
    "processKey": "a1b2c3d4-0000-0000-0000-000000000001",
    "robotName": "…",
    "hostMachineName": "…"
  }
}
```

## uip maestro case instance

Inspect and steer individual **process instances** — one execution of a case process. Shares implementation with [BPMN `instance`](./uip-maestro-bpmn-instances.md) and [Flow `instance`](./uip-maestro-flow-instances.md); refer to either page for the full verb-by-verb reference (`list`, `get`, `pause`, `resume`, `cancel`, `retry`, `migrate`, `variables`, `variables-set`, `variables-all`, `global-variables`, `incidents`, `asset`, `cursors`, `goto`, `element-executions`, `element cancel`/`retry`, `message send`) — every option name, default, and data shape is identical.

**The one real difference**: `-f, --folder-key` is **optional** on every `instance` subcommand for Case (`folderKeyRequired: false` in the shared-commands config), where BPMN and Flow require it. Omit it to scope to your authenticated default folder.

## uip maestro case incident

Read incidents across processes or by ID. Identical implementation to [BPMN `incident`](./uip-maestro-bpmn-incidents.md)/Flow's equivalent — see either page for the full 6-flag `summary` Options table and `get`'s single required `--folder-key`.

## Examples

```bash
# Publish check, then run
uip maestro case process list --folder-key <key>
uip maestro case process get a1b2c3d4-… default --folder-key <key>
uip maestro case process run a1b2c3d4-… <key> --inputs '{"amount":100}'

# Watch it through to completion
JOB_KEY=$(uip maestro case process run a1b2c3d4-… <key> --inputs '{}' --output-filter "Data.jobKey" --output plain)
uip maestro case job traces "$JOB_KEY" --pretty
uip maestro case job status "$JOB_KEY" --detailed

# Diagnose a failing process in one call
uip maestro case processes diagnose a1b2c3d4-… --folder-key <key>
```

## See also

- [Case overview](./uip-maestro-case.md)
- [`uip maestro instance`](./uip-maestro-bpmn-instances.md) / [`uip maestro flow instance`](./uip-maestro-flow-instances.md) — full shared-instance reference
- [`uip maestro incident`](./uip-maestro-bpmn-incidents.md) — full shared-incident reference
- [Orchestrator jobs](./uip-or-jobs.md)