# uip maestro case

> Create, pack, debug, validate, and author Case Management projects using `uip maestro case`, the third Maestro orchestration surface alongside BPMN and Flow.

`uip maestro case` creates, packs, debugs, and authors **Case Management** projects — a third Maestro orchestration surface alongside [BPMN](./uip-maestro-bpmn.md) and [Flow](./uip-maestro-flow.md). A case project models a long-running, human-driven unit of work as a **case plan**: a JSON document (`caseplan.json`) describing stages, tasks, SLAs, triggers, and the entry/exit conditions that move a case between stages — closer to a structured workflow-with-a-lifecycle than a linear process.

The tool ships as the separate `@uipath/case-tool` package, dynamically loaded by `@uipath/maestro-tool` under the `case` branch — every command here is invoked as `uip maestro case <verb>`, never as a standalone `uip case`.

## This resource spans nine pages

- **This page** — concepts, and the project-lifecycle commands: `init`, `pack`, `debug`, `validate`, `spec`.
- [`registry`](./uip-maestro-case-registry.md) — browse/search the automation-resource catalog a case wires tasks to, plus how to bind a task input to a variable.
- [`cases` and `stages`](./uip-maestro-case-cases-stages.md) — read the case-plan's top-level metadata and stage list.
- [`tasks`](./uip-maestro-case-tasks.md) — read, enrich, and describe task definitions within a stage.
- [`task-entry-conditions`](./uip-maestro-case-task-entry-conditions.md) — read the rules that gate when a task becomes runnable.
- [`sla`](./uip-maestro-case-sla.md) — read SLA/escalation rules.
- [`triggers`, `sticky-notes`, `edges`](./uip-maestro-case-triggers.md) — read case triggers, canvas annotations, and stage-to-stage transitions.
- [`case-exit-conditions`, `stage-entry-conditions`, `stage-exit-conditions`](./uip-maestro-case-conditions.md) — read the case-level and stage-level condition rules.
- [`process`, `processes`, `job`, `instances`, `incidents`](./uip-maestro-case-process.md) — deploy and run case instances on Orchestrator.

## Concepts

- **The authoring model: edit `caseplan.json` directly, then `validate`.** There is no CLI-driven mutation path for case content. Author or edit `caseplan.json` by hand (or have an agent do it, guided by the `uipath-maestro-case` skill's JSON-shape references), then run [`uip maestro case validate`](#uip-maestro-case-validate) to check it. The `read` verbs documented on the sibling pages above (`cases get`, `stages list`, `tasks get`, etc.) exist to help you inspect the plan while authoring it this way — they are not part of a write API.
- **Case vs. BPMN vs. Flow** — all three are Maestro orchestration surfaces that pack to `.nupkg` and share runtime primitives (`process`/`job`/`instances`/`incidents`/`registry`), but Case Management's own primary asset is `caseplan.json` (plus a generated `caseplan.json.bpmn`), and its project type is `CaseManagement` in `operate.json`/`project.uiproj` — distinct from BPMN's `.bpmn` and Flow's `.flow`.
- **Validation profiles** — `validate` runs one of four profiles depending on how far along authoring is: `skeleton` (structure only — nodes, edges, identity, types), `skeleton-v2` (skeleton plus SLA/escalation/entry-exit-rule checks, still skipping task content), `strict` (every check, including stage-with-no-tasks, unresolved `$xref` markers, and connector-context completeness — the finished-case gate), and the default `full` profile (lenient, for partially-authored or already-packed files). `--sdd <path>` audits completeness against a spec document and implies `--strict`.
- **`spec`** is a planning tool, not a case-plan mutator: it fetches a normalized description of one Integration Service connector activity or trigger (inputs, outputs, required fields) so you know what to put in `caseplan.json`'s task/trigger definitions before you write them. Find the `--activity-type-id`/`--connection-id` values it needs via [`registry get-connector`/`get-connection`](./uip-maestro-case-registry.md).

## Synopsis

```text
uip maestro case init <name> [--force] [--skip-solution-registration]
uip maestro case pack <project-path> <output-path> [-n, --name <name>] [-v, --version <version>] [package-metadata options...]
uip maestro case debug <project-path> [--folder-id <id>] [--poll-interval <ms>] [--login-validity <minutes>]
uip maestro case validate <file> [--skeleton | --skeleton-v2 | --strict] [--sdd <path>]
uip maestro case spec --type <activity|trigger> --activity-type-id <uuid> --connection-id <id> [--object-name <name>] [--skip-case-shape | --input-details <json>]
```

## uip maestro case init

Create a new Case project with boilerplate files: `project.uiproj`, `operate.json`, `entry-points.json`, `bindings_v2.json`, `package-descriptor.json`, and a minimal `caseplan.json` (only written if one doesn't already exist — re-running `init` never clobbers an authored case plan). If run outside an existing solution, a parent `<name>Solution` is scaffolded automatically and the case project is nested inside it; if run inside one, the project is registered into that solution instead.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<name>` | yes | Case project name. Letters, numbers, underscores, and hyphens only. |

### Options

| Long | Value | Description |
|---|---|---|
| `--force` | flag | Initialize even if the target directory is not empty. Writes files without clearing existing contents. |
| `--skip-solution-registration` | flag | Do not auto-register this project in the surrounding solution. |

### Example

```bash
uip maestro case init my-case-project
```

### Data shape (--output json)

```json
{
  "Code": "CaseInit",
  "Data": {
    "Status": "Created successfully",
    "Path": "/workspace/my-case-project",
    "CasePlan": "/workspace/my-case-project/caseplan.json",
    "CasePlanStatus": "Created",
    "SolutionRegistration": { "Status": "Registered", "Solution": "...", "ProjectId": "..." },
    "AutoCreatedSolution": { "...": "present only when a parent solution was scaffolded" },
    "ProjectArtifacts": { "...": "present only when registered into a parent solution" },
    "NextSteps": "present only when SolutionRegistration.Instructions is set"
  }
}
```

`CasePlanStatus` is `"Created"` on a fresh scaffold or `"Preserved"` when an existing `caseplan.json` was left untouched (re-running `init` on a project you've already authored). `SolutionRegistration` is always present — its `Status` is `"NotInSolution"` rather than the field being omitted when no parent solution exists.

## uip maestro case pack

Pack a Case project directory into a `.nupkg` file, reading `caseplan.json` from the project root.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-path>` | yes | Path to the Case project directory. |
| `<output-path>` | yes | Output directory for the `.nupkg`. |

### Options

| Long | Value | Description |
|---|---|---|
| `-n, --name <name>` | string | Package name. Default: project folder name. |
| `-v, --version <version>` | string | Package version. Default `1.0.0`. |

Also accepts this repo's shared package-metadata options (`--repository-url`/`--repository-commit`/`--repository-branch`/`--repository-type`, `--release-notes`, `--project-url`, `--author`, `--description`) — see any other `pack` command's Options table (for example [`uip maestro pack`](./uip-maestro-bpmn-pack.md)) for the full shared set, which this command registers identically.

### Example

```bash
uip maestro case pack ./my-case-project ./dist --version 1.2.0
```

### Data shape (--output json)

```json
{
  "Code": "CasePack",
  "Data": {
    "Package": "my-case-project.1.2.0.nupkg",
    "Output": "./dist/my-case-project.1.2.0.nupkg"
  }
}
```

A schema error during packing (a malformed `caseplan.json`) is enriched with case-specific guidance before being surfaced as a failure — expect actionable `Instructions`, not a raw parser error.

## uip maestro case debug

Debug a case project by uploading it to Studio Web and running a debug session there — there is no local-only debug mode for Case Management (unlike some other Maestro debug commands).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-path>` | yes | Path to the case project directory. Must contain `project.uiproj`. |

### Options

| Long | Value | Description |
|---|---|---|
| `--folder-id <id>` | integer | Orchestrator folder ID (`OrganizationUnitId`). Auto-detected when omitted. |
| `--poll-interval <ms>` | integer | Polling interval in milliseconds. Default `2000`. |
| `--login-validity <minutes>` | integer | Minimum minutes before token expiration to trigger a refresh. Default `10`. |

Requires an active login (`uip login`) with a resolvable organization, tenant, and access token — fails fast with a specific message naming whichever piece of login state is missing.

### Example

```bash
uip maestro case debug ./my-case-project
```

### Data shape (--output json)

```json
{
  "Code": "CaseDebug",
  "Data": {
    "jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
    "runId": "d4e5f6a7-0000-0000-0000-000000000001",
    "finalStatus": "Completed",
    "solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
    "studioWebUrl": "https://cloud.uipath.com/org/tenant/studio_/debug/e5f6a7b8",
    "elementExecutions": [
      { "elementId": "Stage_1", "status": "Completed" },
      { "elementId": "Stage_2", "status": "Completed" }
    ]
  }
}
```

Keys are kept in their native camelCase (not PascalCased) — this payload is designed to be read programmatically by eval checkers and SDKs, matching the same carve-out used by Flow's debug command and `registry get`. The command exits non-zero when `finalStatus` is anything other than `"Completed"`/`"Successful"`, even though the envelope itself reports `Result: "Success"` — check the exit code, not just the presence of `Data`, in scripts.

## uip maestro case validate

Validate a case management JSON file against Case Management's structural and business rules.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<file>` | yes | Path to the case management JSON file (typically `caseplan.json`). |

### Options

| Long | Description |
|---|---|
| `--skeleton` | Structural checks only (nodes, edges, identity, types). Skips task content, SLAs, escalations, and entry/exit rules — useful during the skeleton phase of authoring. Conflicts with `--skeleton-v2`/`--strict`. |
| `--skeleton-v2` | Skeleton checks plus SLA, escalation, and entry/exit rule checks. Still skips task content. Conflicts with `--skeleton`/`--strict`. |
| `--strict` | Every check, plus the strict set: a stage with no tasks, unresolved `$xref` markers, a hoisted `conditionExpression`, formal-argument/output-binding shapes, and connector-context completeness. The finished-case gate. Conflicts with `--skeleton`/`--skeleton-v2`. |
| `--sdd <path>` | Audit the caseplan for completeness against the given SDD (spec document) — every stage, task, task type, condition row, SLA, trigger, and case variable it declares must be present. Implies `--strict`. |

Omitting all four runs the default `full` profile: lenient, so partially-authored or already-packed files still validate.

### Examples

```bash
uip maestro case validate case.json
uip maestro case validate case.json --skeleton
uip maestro case validate case.json --strict
uip maestro case validate case.json --sdd ./spec.md
```

### Data shape (--output json)

```json
{
  "Code": "CaseValidate",
  "Data": {
    "File": "case.json",
    "Status": "Valid",
    "Warnings": "2 warning(s):\n  - [stages[0].tasks[1]] ...",
    "Issues": [
      { "Code": "UNRESOLVED_REFERENCE", "Path": "stages[0].tasks[1]", "Message": "...", "Severity": "warning" }
    ]
  }
}
```

`Profile: "strict"` is added to `Data` only when `--strict` (or `--sdd`) was passed. `Warnings`/`Issues` are present only when the valid file still produced warnings. On failure (`Result: "Failure"`, exit 1), `Data.Issues` carries every error and warning with a stable `Code`, `Path`, `Message`, and `Severity` — parse this array rather than the human-readable `Instructions` text if you're driving a repair loop.

## uip maestro case spec

Generate a normalized `ConnectorTaskSpec` — everything needed to construct a runnable Integration Service activity or trigger task inside a case plan. Looks up the type in the local TypeCache, lists Integration Service connections for the connector, and fetches Integration Service metadata.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--type <type>` | `activity` \| `trigger` | **yes** | Which TypeCache to look up. |
| `--activity-type-id <uuid>` | UUID | **yes** | Studio Web `uiPathActivityTypeId`. Find it via [`registry pull`](./uip-maestro-case-registry.md) + reading the `typecache-{activities,triggers}-index.json` cache file, or `registry get-connector`. |
| `--connection-id <id>` | UUID | **yes** | Connection ID. List candidates with [`registry get-connection --type typecache-{activities,triggers} --activity-type-id <uuid>`](./uip-maestro-case-registry.md). |
| `--object-name <name>` | string | no | Override the TypeCache `objectName`. Required for entity-typed curated triggers whose TypeCache stores a placeholder (e.g. Data Service `{tenantEntityName\|folderEntityName}`) — pick a real entity name. |
| `--skip-case-shape` | flag | no | Omit `caseShape` (`inputs[]`/`outputs[]`/`context[]`) from the response — use during planning when you only need the connector contract. Mutually exclusive with `--input-details`. |
| `--input-details <json>` | JSON | no | Pre-fill values folded into the generated `caseShape`. Shape differs by `--type`: activity accepts `{bodyParameters, queryParameters, pathParameters, filter}`; trigger accepts `{eventParameters, filter}`. Mutually exclusive with `--skip-case-shape`. |

### Examples

```bash
# Curated connector activity (Send Email)
uip maestro case spec --type activity \
  --activity-type-id c7ce0a96-2091-3d94-b16f-706ebb1eb351 \
  --connection-id fc82e610-c454-4bc7-a1a5-b5aa529d1ba6
```

```bash
# Curated connector trigger (Email Received)
uip maestro case spec --type trigger \
  --activity-type-id 7dc57f24-894c-5ae2-a902-66056fa40609 \
  --connection-id fc82e610-c454-4bc7-a1a5-b5aa529d1ba6
```

### Data shape (--output json)

```json
{
  "Code": "ConnectorTaskSpec",
  "Data": {
    "specVersion": 1,
    "identity": {
      "target": "activity",
      "uiPathActivityTypeId": "c7ce0a96-2091-3d94-b16f-706ebb1eb351",
      "connectorKey": "uipath-microsoft-outlook365",
      "objectName": "send-mail-v2",
      "typecacheEntry": { "displayName": "Send Email" }
    },
    "operation": { "name": "POST", "verb": "create", "httpMethod": "POST", "path": "/hubs/productivity/send-mail-v2" },
    "inputs": { "bodyFields": [{ "name": "message.toRecipients", "required": true }] }
  }
}
```

A trigger spec's `operation` shape differs (`eventMode`/event name instead of an HTTP verb/path) — see the second example above.

## Related

- [`registry`](./uip-maestro-case-registry.md) — discover resources to reference in a case plan, and how to bind a task input to a variable.
- [`cases` and `stages`](./uip-maestro-case-cases-stages.md) — inspect case-plan metadata and stages.
- [`tasks`](./uip-maestro-case-tasks.md) — inspect, enrich, and describe task definitions.
- [`task-entry-conditions`](./uip-maestro-case-task-entry-conditions.md) — inspect task-level entry rules.
- [`sla`](./uip-maestro-case-sla.md) — inspect SLA/escalation rules.
- [`triggers`, `sticky-notes`, `edges`](./uip-maestro-case-triggers.md) — inspect triggers, canvas notes, and transitions.
- [conditions](./uip-maestro-case-conditions.md) — inspect case-level and stage-level entry/exit condition rules.
- [`process`, `processes`, `job`, `instances`, `incidents`](./uip-maestro-case-process.md) — deploy and run case instances.
- [`uip maestro`](./uip-maestro-bpmn.md) — BPMN orchestration, the sibling surface.
- [`uip maestro flow`](./uip-maestro-flow.md) — Flow orchestration, the other sibling surface.

## See also

- [Maestro tool overview](./uip-maestro-bpmn.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)