# uip maestro case tasks

> Syntax and options for `uip maestro case tasks`, which reads and enriches tasks within a stage in a case management definition JSON file, plus the JSON field reference for hand-authoring one.

A **task** is a unit of work inside a stage of a case management definition — a process run, an agent invocation, an API workflow, an RPA job, a human action item, a timer wait, a connector activity, or a wait for an inbound connector event. Task entries live inside a stage's lanes in the case-definition JSON file (the same file structure [`stages`](./uip-maestro-case-cases-stages.md) and [`task-entry-conditions`](./uip-maestro-case-task-entry-conditions.md) operate on); `uip maestro case tasks` reads and enriches them.

For entry rules that gate when a task becomes runnable, see [`uip maestro case task-entry-conditions`](./uip-maestro-case-task-entry-conditions.md). For the overall Case Management concept model, see [`uip maestro case`](./uip-maestro-case.md).

## Concepts

- **Lane** — tasks within a stage are grouped into parallel lanes (index `0`, `1`, `2`, …); tasks in the same lane run sequentially, tasks in different lanes run in parallel. `lane` defaults to `0` when hand-authoring a task.
- **Task type** — one of `process`, `action`, `agent`, `api-workflow`, `rpa`, `external-agent`, `wait-for-timer`, `wait-for-connector`, `execute-connector-activity`, `case-management`. Connector-backed types (`execute-connector-activity`, `wait-for-connector`) use a different field shape than the others (see below).
- **Enrichment** — several task types need input/output schema and binding metadata pulled from the platform (a process's real input/output contract, a connector activity's field schema) before Studio Web can render them meaningfully. `tasks enrich` and `tasks describe` are lookup commands for that metadata, useful for discovering what to write into a task's JSON before hand-authoring it.

## Synopsis

```text
uip maestro case tasks get <file> <stage-id> <task-id>
uip maestro case tasks enrich --type <type> --id <id> [--element-id <id>]
uip maestro case tasks describe --type <type> --id <id> [--connection-id <id>]
```

## Task JSON fields

Tasks are added, edited, and removed by hand in `caseplan.json`'s stage lane arrays, then validated with [`uip maestro case validate`](./uip-maestro-case.md#uip-maestro-case-validate). Field reference:

**A non-connector task** — task types: `process`, `action`, `agent`, `api-workflow`, `rpa`, `external-agent`, `wait-for-timer`, `case-management` (connector-backed types below are separate). Fields: `displayName`, `name` (process/workflow name), `folderPath`, `lane` (parallel-lane index, default `0`), `shouldRunOnlyOnce`, `description`, `isRequired`; `action`-type only: `taskTitle`, `priority` (`Low`\|`Medium`\|`High`\|`Critical`, default `Medium`), `recipient` (email; also sets `assignmentCriteria` to `user`). An enriched task (bindings/inputs/outputs looked up from the platform) additionally carries a stable `elementId` and `enriched: true` — use [`tasks enrich`](#uip-maestro-case-tasks-enrich) to fetch that payload before hand-writing it in.

**A connector-backed task** — task type `execute-connector-activity` (activity) or `wait-for-connector` (trigger), identified by a TypeCache `uiPathActivityTypeId` and a connection ID. Carries a `serviceType` of `Intsvc.ActivityExecution` (activity) or `Intsvc.WaitForEvent` (trigger). Input values: for an activity, keyed by input name (`body`, `pathParameters`, `queryParameters`); for a trigger, values under `body` become event filter parameters (a `filters.expression` is generated from them, e.g. `(project == 'PROJ' && issuetype == 'Bug')`) and also populate `queryParams`/`parameters`. Use [`tasks describe`](#uip-maestro-case-tasks-describe) to discover real input names and the full enrichment payload before hand-writing a task.

**Updating a task** — merge the same `displayName`/`name`/`folderPath`/`shouldRunOnlyOnce`/`description`/`isRequired` fields onto the existing task object (unlisted fields keep their current value). `name`/`folderPath` have no effect on a `wait-for-timer` task, which has no `data` block.

**Removing a task** — delete its entry from the stage's lane array directly; drop the lane entirely if it becomes empty.

After any hand-edit, run `uip maestro case validate`.

## uip maestro case tasks get

Print a single task from a stage.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<file>` | yes | Path to the case management JSON file. |
| `<stage-id>` | yes | ID of the stage containing the task. |
| `<task-id>` | yes | ID of the task to retrieve. |

### Example

```bash
uip maestro case tasks get case.json Stage_1 ta1b2c3d
```

### Data shape (--output json)

```json
{
  "Code": "TaskFound",
  "Data": {
    "StageId": "Stage_1",
    "Lane": 0,
    "Index": 0,
    "Task": { "id": "ta1b2c3d", "type": "process", "displayName": "Process invoice" }
  }
}
```

## uip maestro case tasks enrich

Look up a task type's real input/output schema and bindings from the platform, without writing to any file. Visible in `--help`.

:::note
Use this to preview what `tasks add --task-type-id` will produce before committing it to a file. For connector activities/triggers specifically, use [`tasks describe`](#uip-maestro-case-tasks-describe) instead — `enrich` covers the other enrichable types (`process`, `agent`, `rpa`, `action`, `api-workflow`, `case-management`, `flow-process`).
:::

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--type <type>` | one of the enrichable types | **yes** | Task type. |
| `--id <id>` | string | **yes** | Unique ID of the task (entityKey or Action App ID, depending on type). |
| `--element-id <id>` | string | no | Element ID to scope the variable binding to. |

### Example

```bash
uip maestro case tasks enrich --type process --id a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{
  "Code": "TaskEnriched",
  "Data": {
    "name": "InvoiceProcess",
    "folderPath": "Shared",
    "inputs": [],
    "outputs": []
  }
}
```

The exact `Data` shape depends on `--type` — a raw enrichment payload from the platform, not normalized to one fixed schema.

## uip maestro case tasks describe

Describe a task type's input/output metadata for binding discovery — the widest type coverage of any lookup command here (adds `connector-activity`, `connector-trigger`, `external-workflow`, and `external-agent` on top of everything `enrich` supports). Visible in `--help`.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--type <type>` | one of the describable types | **yes** | Task type — see the list above. |
| `--id <id>` | string | **yes** | Unique ID of the task (entityKey or Action App ID). |
| `--connection-id <id>` | UUID | conditionally | **Required** for `connector-activity`, `connector-trigger`, `external-workflow`, and `external-agent` — the command fails fast with an explicit error if omitted for these types. Not used for other types. |

`external-workflow` and `external-agent` describe identically to `connector-activity` (same Integration Service enrichment pipeline, same `--connection-id` requirement) but resolve their type ID against a different TypeCache index, since Studio Web serves them from a separate catalog.

### Example

```bash
uip maestro case tasks describe --type connector-activity \
  --id a1b2c3d4-0000-0000-0000-000000000001 \
  --connection-id b2c3d4e5-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{
  "Code": "TaskDescribed",
  "Data": {
    "inputs": [{ "name": "body", "body": {} }],
    "outputs": [{ "name": "response" }]
  }
}
```

An `enrichment` field is included only when the underlying lookup returns one.

## Related

- [uip maestro case](./uip-maestro-case.md) — concepts and the full subsystem directory.
- [uip maestro case task-entry-conditions](./uip-maestro-case-task-entry-conditions.md) — rules that gate when a task becomes runnable.
- [uip maestro case cases & stages](./uip-maestro-case-cases-stages.md) — the stage a task lives inside.

## See also

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