# @uipath/case-tool

CLI plugin for managing UiPath case management resources. Provides commands to pull, cache, and list resources from the UiPath platform.

## Installation

This package is a plugin for `uip`. It is loaded automatically when installed in the CLI's plugin directory.

## Prerequisites

You must be logged in before using any commands:

```bash
uip login
```

## Commands

All commands are available under the `case` prefix:

```
uip case <command>
```

### `registry pull`

Fetch and cache all resource types from the UiPath platform.

```bash
uip case registry pull [options]
```

| Option | Description |
| :--- | :--- |
| `-f, --force` | Force refresh, ignore local cache |
| `-s, --solutionId <id>` | Include entities from a specific solution |
| `--output <type>` | Output format: `json`, `table`, `yaml`, `plain` (default: `json`) |

**Resource types pulled:**

| Type | Description |
| :--- | :--- |
| `agent` | Agent processes |
| `process` | RPA workflows |
| `api` | API workflows |
| `processOrchestration` | Agentic processes |
| `caseManagement` | Case management workflows |
| `typecache` | Studio activities (CrossPlatform / ProcessOrchestration) |
| `action-apps` | Deployed human action apps |
| `solution` | Solution entities (requires `--solutionId`) |

**Cache behavior:** Results are cached for 30 minutes in `~/.uipcli/case-resources/`. Subsequent `pull` calls within that window return cached data unless `--force` is passed.

**Example output:**

```json
{
  "Result": "Success",
  "Code": "PullResourcesSuccess",
  "Data": {
    "TotalNodesCount": 142,
    "FromCache": false,
    "ResourceTypes": [
      { "Type": "agent", "NodesCount": 12, "FromCache": false, "CacheWritten": true },
      { "Type": "process", "NodesCount": 87, "FromCache": false, "CacheWritten": true }
    ]
  }
}
```

---

### `registry list`

List all locally cached resources.

```bash
uip case registry list [options]
```

| Option | Description |
| :--- | :--- |
| `--output <type>` | Output format: `json`, `table`, `yaml`, `plain` (default: `json`) |
| `-q, --quiet` | Quiet mode, no output |

If no cache exists, the command automatically fetches live data from the platform.

---

### `validate`

Validate a case management definition JSON file against all case management rules (structure, stages, edges, conditions).

```bash
uip case validate <file>
```

Returns a list of errors and warnings. Exits with code `1` if any errors are found.

---

### `cases`

Manage local case management definition JSON files.

```bash
uip case cases <action>
```

| Subcommand | Description |
| :--- | :--- |
| `add` | Create a new case management definition JSON file |
| `edit <file>` | Edit root-level properties of an existing definition |
| `validate <file>` | Validate a definition file (alias for `uip case validate`) |

**`cases add` options:**

| Option | Description |
| :--- | :--- |
| `-n, --name <name>` | Name of the case management definition *(required)* |
| `-f, --file <path>` | Output path for the new JSON file *(required)* |
| `--case-identifier <id>` | Case identifier string (defaults to name) |
| `--identifier-type <type>` | `constant` or `external` (default: `constant`) |
| `--case-app-enabled` | Enable the case app for this definition |

**`cases edit` options:**

| Option | Description |
| :--- | :--- |
| `-n, --name <name>` | New name |
| `--case-identifier <id>` | New case identifier |
| `--identifier-type <type>` | New identifier type |
| `--case-app-enabled` | Enable the case app |

---

### `stages`

Manage stage nodes within a case management definition JSON file.

```bash
uip case stages <action> <file> [stage-id]
```

| Subcommand | Description |
| :--- | :--- |
| `add <file>` | Add a new stage node |
| `edit <file> <stage-id>` | Edit an existing stage's label |
| `get <file> <stage-id>` | Print a stage and its connected edges |
| `remove <file> <stage-id>` | Remove a stage and its connected edges |

**`stages add` options:**

| Option | Description |
| :--- | :--- |
| `-l, --label <label>` | Display label for the stage |
| `-t, --type <type>` | `stage`, `exception`, or `trigger` (default: `stage`) |

---

### `edges`

Manage edges within a case management definition JSON file.

```bash
uip case edges <action> <file> [edge-id]
```

| Subcommand | Description |
| :--- | :--- |
| `add <file>` | Add a new edge between two nodes |
| `edit <file> <edge-id>` | Edit an existing edge |
| `get <file> <edge-id>` | Print an edge |
| `remove <file> <edge-id>` | Remove an edge |
| `validate <file> <edge-id>` | Validate a single edge in context |
| `list <file>` | List all edges in a definition |

**`edges add` options:**

| Option | Description |
| :--- | :--- |
| `-s, --source <id>` | Source stage or trigger ID *(required)* |
| `-t, --target <id>` | Target stage ID *(required)* |
| `-l, --label <label>` | Display label |
| `--source-handle <dir>` | `right`, `left`, `top`, `bottom` (default: `right`) |
| `--target-handle <dir>` | `right`, `left`, `top`, `bottom` (default: `left`) |
| `--z-index <number>` | Z-index layer for rendering order |

Edge type is inferred from the source node: Trigger → `TriggerEdge`, Stage → `Edge`.

**`edges validate` checks:**
- Source and target nodes exist
- No duplicate conditions on edges from the same source node

---

## Local Cache

Resources are stored in `~/.uipcli/case-resources/` as JSON files:

| File | Contents |
| :--- | :--- |
| `{type}-index.json` | Full resource array for that type |
| `{type}-index.meta.json` | Sync metadata: `lastSync`, `count`, `hash` |

Change detection uses SHA-256 hashing — if the fetched data is identical to the cache, only the timestamp is updated and the index is not rewritten.

## API Endpoints

| Resource type | Endpoint |
| :--- | :--- |
| `agent`, `process`, `api`, `processOrchestration`, `caseManagement` | `/{accountId}/{tenantId}/resourcecatalog_/Entities/Process?entitySubType=<type>` |
| `action-apps` | `/{accountId}/apps_/default/api/v1/default/action-apps?state=deployed` |
| `typecache` | `/{accountId}/studio_/typecache/api/Activities/SearchActivities` |
| `solution` | `/{accountId}/studio_/backend/api/resourcebuilder/solutions/{solutionId}/entities` |
