# uip maestro case registry

> Browse and search the Maestro Case Management registry of activities, triggers, connectors, and other automation resources using `uip maestro case registry`.

`uip maestro case registry` browses and searches the **Case Management registry** — a local, cached catalog of the automation resources (processes, agents, APIs, flows, connector activities/triggers, action apps, and optionally an in-progress solution's own resources) a case definition can wire tasks to. Pull the registry once per session, then search or fetch resources by identifier while authoring a case.

For the overall `uip maestro case` subsystem and how registry resources feed into task authoring, see the [overview](./uip-maestro-case.md).

## Synopsis

```
uip maestro case registry pull [-f, --force] [-s, --solution-id <solutionId>]
uip maestro case registry search [keyword] [-t, --type <type>] [-f, --filter <filter>] [--local]
uip maestro case registry list [--local]
uip maestro case registry get <identifier> [-t, --type <type>] [--connection-id <id>] [--local]
uip maestro case registry get-connector -t, --type <type> --activity-type-id <id>
uip maestro case registry get-connection -t, --type <type> --activity-type-id <id>
```

Typical workflow:

1. `uip maestro case registry pull` — fetch and cache the full resource registry (run once per session).
2. `uip maestro case registry search <keyword>` — find a resource.
3. `uip maestro case registry get <identifier>` — inspect its full schema.
4. `uip maestro case registry get <identifier> --output-filter "Node.inputDefinition.fields"` — extract just the input fields.

## Concepts

- **Resource types** — the registry indexes 17 resource types: `agent`, `process`, `api`, `processOrchestration`, `caseManagement`, `flow`, `action-apps`, `solution`, plus 9 `typecache-*` connector index files split by catalog source (`typecache-activities`, `typecache-triggers`, `typecache-packages`, and the `-external-automation-*`/`-external-agent-*` variants of each). They're kept as separate cache files because the underlying catalogs are disjoint — merging them would make each pull overwrite the previous type's entries.
- **`--local` mode** — `search`, `list`, and `get` accept `--local` to search only in-solution sibling project resources instead of the tenant-wide cache. Requires a `.uipx` file in the current directory or one of its two parent directories; the identifier for `get --local` is the sibling's resource key or its `.uipx` project ID.
- **`solution` resources** — the `solution` resource type is cached only when `pull` is given `--solution-id <id>`; searching/getting `--type solution` without having pulled it first returns an explicit hint to run `pull --solution-id` first.
- **Connector enrichment** — `get` automatically enriches `typecache-activities`/`typecache-triggers` matches with live connector metadata (looked up by the entry's `uiPathActivityTypeId`) when possible; pass `--connection-id` to get connection-specific custom-field metadata. This enrichment is silently skipped (not an error) if the lookup fails.
- **`get-connector` / `get-connection`** — lower-level lookups against the local TypeCache index only (not the general resource cache): `get-connector` resolves one connector activity/trigger entry plus its connector config by `--activity-type-id`; `get-connection` does the same lookup and then fetches the connector's available connections from Integration Service.

## uip maestro case registry pull

Fetch and cache all resource types. Runs all types in parallel and reports a per-type breakdown, including any that failed.

### Options

| Short | Long | Value | Description |
|---|---|---|---|
| `-f` | `--force` | flag | Ignore the cache and re-fetch every resource type. |
| `-s` | `--solution-id <solutionId>` | string | Also pull and cache the given solution's own resources (the `solution` resource type). |

### Example

```bash
uip maestro case registry pull
```

### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "PullResourcesSuccess",
  "Data": {
    "TotalNodesCount": 128,
    "FromCache": false,
    "ResourceTypes": [
      {
        "Type": "typecache-activities",
        "NodesCount": 80,
        "FromCache": false,
        "AgeMinutes": null,
        "CacheWritten": true,
        "Info": null
      }
    ],
    "Errors": null
  }
}
```

`Result` is `"PartialSuccess, N failed"` (not `"Success"`) when one or more resource types fail to pull — `Errors` then lists each failed type with its error message; the successfully-pulled types are still cached and reflected in `ResourceTypes`.

## uip maestro case registry search

Search cached resources by keyword and/or field filters. At least one of `[keyword]` or `--filter` is required.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `[keyword]` | no* | Free-text keyword to search for. |

\* Either `[keyword]`, `--filter`, or both must be given — omitting both fails before any lookup.

### Options

| Short | Long | Value | Description |
|---|---|---|---|
| `-t` | `--type <type>` | enum | Limit the search to one resource type. One of the searchable types — see [Concepts](#concepts) for the full 17-type list (all `RESOURCE_TYPES` values are valid here). |
| `-f` | `--filter <filter>` | string | Field filters: `field=value` or `field:operator=value`, comma-separated for multiple (e.g. `name:contains=Apple,category=Pipelines`). Fields: `name`, `title`, `description`, `category`, `connectorKey`. Operators: `equals`, `contains`, `in`, `startsWith`, `endsWith`. |
| — | `--local` | flag | Search only in-solution sibling resources. See [Concepts](#concepts). |

### Examples

```bash
uip maestro case registry search invoice
```

```bash
uip maestro case registry search --filter "name:contains=Apple,category=Pipelines"
```

### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ResourceSearchSuccess",
  "Data": {
    "Keyword": "invoice",
    "Filters": null,
    "Type": null,
    "Local": false,
    "ResultCount": 1,
    "Resources": [
      {
        "resourceType": "typecache-activities",
        "resource": {
          "name": "InvoiceParser",
          "uiPathActivityTypeId": "a1b2c3d4-0000-0000-0000-000000000001"
        }
      }
    ],
    "FailedTypes": null,
    "Hint": null
  }
}
```

`Hint` is populated (rather than omitted) specifically when `--type solution` returns zero results and `--local` wasn't passed — it points you at `registry pull --solution-id <id>`. `FailedTypes` lists any resource types that errored during the search (partial results are still returned for the types that succeeded).

## uip maestro case registry list

List every cached resource, grouped by type. Does not hit the network — reflects whatever `pull` last cached; run `pull` first (or again) to refresh.

### Options

| Long | Value | Description |
|---|---|---|
| `--local` | flag | List only in-solution sibling resources instead of the tenant-wide cache. See [Concepts](#concepts). |

### Example

```bash
uip maestro case registry list
```

### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ResourceListSuccess",
  "Data": {
    "ResourcesCount": 128,
    "Local": false,
    "ResourceTypes": [
      { "Type": "typecache-activities", "Count": 80 },
      { "Type": "typecache-triggers", "Count": 48 }
    ],
    "resources": []
  }
}
```

`--local` resolves the solution and scans its resource tree directly (no cache involved); a missing solution (no `.uipx` found) is reported as a clean error rather than an empty list.

## uip maestro case registry get

Get one or more full resource records by identifier.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<identifier>` | yes | The resource's `entityKey` (process-like types) or `id` (action-apps) — see each type's id field via [Concepts](#concepts). With `--local`, the sibling project's resource key or `.uipx` project ID instead. |

### Options

| Short | Long | Value | Description |
|---|---|---|---|
| `-t` | `--type <type>` | enum | Limit the lookup to one resource type (same set as `search --type`). |
| — | `--connection-id <id>` | string | Connection ID for connector-specific Integration Service field metadata (custom fields). Only applies to `typecache-*` activity/trigger matches. |
| — | `--local` | flag | Resolve against in-solution sibling resources instead of the tenant cache. See [Concepts](#concepts). |

### Example

```bash
uip maestro case registry get a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ResourceGetSuccess",
  "Data": {
    "MatchCount": 1,
    "Local": false,
    "Resources": [
      {
        "ResourceType": "typecache-activities",
        "Resource": {
          "uiPathActivityTypeId": "a1b2c3d4-0000-0000-0000-000000000001",
          "name": "InvoiceParser"
        }
      }
    ]
  }
}
```

Zero matches is a failure (`Code`-less error response), not an empty success — the error's `Instructions` differ by mode: a `--local` miss suggests re-checking the sibling's resource key or project ID via `registry list --local`; a `--type solution` miss suggests running `pull --solution-id` first; anything else just reports "no resource found."

## uip maestro case registry get-connector

Look up a single connector activity/trigger entry (and its connector config) directly from the local TypeCache index, bypassing the general resource search.

### Options

| Short | Long | Value | Required | Description |
|---|---|---|---|---|
| `-t` | `--type <type>` | enum | **yes** | TypeCache index to look in: `typecache-activities`, `typecache-triggers`, `typecache-external-automation-activities`, `typecache-external-automation-triggers`, `typecache-external-agent-activities`, or `typecache-external-agent-triggers`. |
| — | `--activity-type-id <id>` | string | **yes** | The `uiPathActivityTypeId` to look up. |

### Example

```bash
uip maestro case registry get-connector --type typecache-activities --activity-type-id a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ConnectorGetSuccess",
  "Data": {
    "Entry": {
      "uiPathActivityTypeId": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "InvoiceParser"
    },
    "Config": { "connectorKey": "uipath-connector-a" }
  }
}
```

## uip maestro case registry get-connection

Look up a connector activity/trigger (same lookup as `get-connector`), then fetch its available Integration Service connections.

### Options

| Short | Long | Value | Required | Description |
|---|---|---|---|---|
| `-t` | `--type <type>` | enum | **yes** | Same TypeCache index choices as `get-connector`. |
| — | `--activity-type-id <id>` | string | **yes** | The `uiPathActivityTypeId` to look up. |

### Example

```bash
uip maestro case registry get-connection --type typecache-activities --activity-type-id a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ConnectionGetSuccess",
  "Data": {
    "Entry": { "uiPathActivityTypeId": "a1b2c3d4-0000-0000-0000-000000000001" },
    "Config": { "connectorKey": "uipath-connector-a" },
    "Connections": [
      { "id": "b2c3d4e5-0000-0000-0000-000000000001", "name": "Default" }
    ]
  }
}
```

## Binding a task input to a variable

A task's input is wired to a literal value/expression or another task's output by editing the case management JSON schema file directly. Field reference: a task's input at a dot-separated `<field-path>` (`<input-name>[.<key1>[.<key2>...]]` — no dots sets `input.value` directly; each dot segment traverses one property level, e.g. `body.body.body` for a connector activity's nested request body) takes either a literal string, an expression with an allowed prefix (`=vars.`, `=bindings.`, `=js:`, `=metadata.`, `=datafabric.`, `=orchestrator.JobAttachments`, `=response`, `=result`, `=Error`, `=jsonString:`), or a generated `=vars.<id>` expression when sourcing another task's output. Edit `caseplan.json`'s task input directly to set any of these, then run `uip maestro case validate <file>`.

## Related

- [uip maestro case](./uip-maestro-case.md) — overview and the rest of the Case Management subsystem.

## See also

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