# @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 maestro case <command>
```

### `registry pull`

Fetch and cache all resource types from the UiPath platform.

```bash
uip maestro 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-activities` | Connector activities (Integration Service) |
| `typecache-triggers` | Connector triggers (Integration Service) |
| `action-apps` | Deployed human action apps |
| `solution` | Solution entities (requires `--solutionId`) |

**Cache behavior:** Results are cached for 30 minutes in `~/.uip/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 search`

Search for resources by keyword and/or structured field filters.

```bash
uip maestro case registry search [keyword] [options]
```

| Option | Description |
| :--- | :--- |
| `-t, --type <type>` | Limit search to a specific resource type (see types above) |
| `-f, --filter <filter>` | Field filters, e.g. `name:contains=Apple,category=Pipelines` |
| `--output <type>` | Output format: `json`, `table`, `yaml`, `plain` |

**Filter syntax:**

```
field=value                   equality (default)
field:contains=value          field contains value
field:startsWith=value        field starts with value
field:endsWith=value          field ends with value
field:in=value1|value2        field matches any of the values
field1=v1,field2=v2           multiple conditions (AND logic)
```

Filterable fields: `name`, `description`, `category`, `tags`

**Examples:**

```bash
# Search connectors by keyword
uip maestro case registry search outlook --type typecache-activities

# Filter by category
uip maestro case registry search --filter "category:contains=Salesforce" --type typecache-activities

# Search across all resource types
uip maestro case registry search "send email"
```

---

### `registry get`

Get a resource by its identifier. For connector activities and triggers, automatically enriches the result with input/output field metadata from Integration Service.

```bash
uip maestro case registry get <identifier> [options]
```

| Argument/Option | Description |
| :--- | :--- |
| `<identifier>` | `entityKey` (process-types), `id` (action-apps), or `uiPathActivityTypeId` (connectors) |
| `--connection-id <id>` | Connection ID for connection-specific IS field metadata (custom fields). Only applies to `typecache-activities` / `typecache-triggers` results. |
| `--output <type>` | Output format: `json`, `table`, `yaml`, `plain` |

**Connector enrichment:** When the matched resource is a `typecache-activities` or `typecache-triggers` entry, the result is automatically enriched with `inputDefinition` and `outputDefinition` fields fetched from Integration Service. These describe the available input/output fields for that connector activity, including field types, required flags, descriptions, and enum values.

- Without `--connection-id`: returns standard/base fields for the connector object.
- With `--connection-id`: returns connection-specific fields including custom fields tied to that account.

If Integration Service is unavailable or the activity has no associated IS object (non-curated), the resource is returned as-is without enrichment.

**Examples:**

```bash
# Get a connector activity with IS field metadata
uip maestro case registry get 696568b6-0a38-3a97-8831-38e3cf3588fa

# Get with connection-specific custom fields
uip maestro case registry get 696568b6-0a38-3a97-8831-38e3cf3588fa --connection-id <your-connection-id>

# Get an agent by entityKey
uip maestro case registry get my-agent-entity-key
```

---

### `registry list`

List all locally cached resources.

```bash
uip maestro 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 maestro 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 maestro case cases <action>
```

| Subcommand | Description |
| :--- | :--- |
| `add` | Create a new case management definition JSON file |
| `update <file>` | Update root-level properties of an existing definition |
| `validate <file>` | Validate a definition file (alias for `uip maestro 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 update` 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 maestro case stages <action> <file> [stage-id]
```

| Subcommand | Description |
| :--- | :--- |
| `add <file>` | Add a new stage node |
| `update <file> <stage-id>` | Update 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 maestro case edges <action> <file> [edge-id]
```

| Subcommand | Description |
| :--- | :--- |
| `add <file>` | Add a new edge between two nodes |
| `update <file> <edge-id>` | Update 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 `~/.uip/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-activities` | `/{accountId}/studio_/typecache/api/Activities/SearchActivities` |
| `typecache-triggers` | `/{accountId}/studio_/typecache/api/Activities/SearchTriggers` |
| `solution` | `/{accountId}/studio_/backend/api/resourcebuilder/solutions/{solutionId}/entities` |
