# uip or queue-roi

> Syntax and options for `uip or queue-roi`, which manages the Business ROI configuration of an Orchestrator queue.

`uip or queue-roi` manages the Business ROI configuration of a queue: the manual time a human spends per item, the item volume, the employee cost, and the cost per item. Each queue has at most one ROI configuration. For the same configuration on a process, refer to [`uip or process-roi`](./uip-or-process-roi.md).

For the cross-resource conventions (auth, folder scoping, key types, output envelope), refer to the [`uip or` overview](./uip-or.md).

:::note
Every verb needs the `OR.BusinessValue` scope on the login, the BusinessValue folder permission that matches the verb (View, Create, Edit, or Delete), and the Business ROI feature enabled on the tenant.
:::

## Synopsis

```
uip or queue-roi get     <queue> [--folder-path <path> | --folder-key <key>]
uip or queue-roi create  <queue> --manual-time <number> [value options] [--disabled] [--folder-path <path> | --folder-key <key>]
uip or queue-roi update  <queue> [value options] [--no-volume] [--no-employee-cost] [--no-cost-per-item] [--enabled | --disabled] [--folder-path <path> | --folder-key <key>]
uip or queue-roi delete  <queue> --yes [--folder-path <path> | --folder-key <key>]
```

## Verbs

| Verb | Purpose |
|---|---|
| `get` | Get the ROI configuration of a queue. Reports `Configured: false` when none exists. |
| `create` | Create the ROI configuration of a queue. Fails when one exists. |
| `update` | Update the ROI configuration of a queue. Values you do not pass keep their current setting. |
| `delete` | Delete the ROI configuration of a queue. |

## Arguments

Every verb takes the same positional argument.

| Name | Required | Purpose |
|---|---|---|
| `<queue>` | yes | Queue name or key (GUID). A name needs `--folder-path` or `--folder-key` when it exists in more than one folder you can see. Find queues with [`uip or queues list`](./uip-or-queues.md). |

## Folder options

Every verb accepts these options. They scope a name lookup and are not needed for a key.

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--folder-path` | path | — | Folder path the queue name is looked up in (for example, `Shared`). |
| — | `--folder-key` | GUID | — | Folder key the queue name is looked up in. |

## uip or queue-roi get

Get the ROI configuration of a queue. When the queue has no ROI configuration, the command succeeds with `Configured: false`.

### Examples

```bash
uip or queue-roi get InvoiceQueue --folder-path Shared
uip or queue-roi get a1b2c3d4-0000-0000-0000-000000000010
uip or queue-roi get a1b2c3d4-0000-0000-0000-000000000010 \
    --output-filter 'Configured'
```

### Data shape (--output json)

```json
{
  "Code": "QueueRoiGet",
  "Data": {
    "QueueKey": "a1b2c3d4-0000-0000-0000-000000000010",
    "QueueName": "InvoiceQueue",
    "Folder": "Shared",
    "Configured": true,
    "Key": "e5f6a7b8-0000-0000-0000-000000000001",
    "Enabled": true,
    "ManualTimePerItem": 12,
    "ManualTimeUnit": "Minutes",
    "ProcessVolume": 4000,
    "ProcessVolumePeriod": "Month",
    "EmployeeCost": 65000,
    "EmployeeCostPeriod": "Annual",
    "ManualCostPerItem": null,
    "Currency": "Usd"
  }
}
```

A queue with no ROI configuration returns only `QueueKey`, `QueueName`, `Folder`, and `Configured: false`.

| Field | Description |
|---|---|
| `Key` | Key of the ROI configuration. |
| `Enabled` | Whether ROI tracking is on for the queue. |
| `ManualTimePerItem` / `ManualTimeUnit` | Manual time a human spends per item, and its unit. |
| `ProcessVolume` / `ProcessVolumePeriod` | Items processed per period. `null` when not set. |
| `EmployeeCost` / `EmployeeCostPeriod` | Fully loaded employee cost, in USD, over the period. `null` when not set. |
| `ManualCostPerItem` | Manual cost per item, in USD. `null` when not set, in which case the Orchestrator UI computes it from the other values. |
| `Currency` | Currency of the cost values. |

## uip or queue-roi create

Create the ROI configuration of a queue. Requires `--manual-time`. Fails when the queue already has an ROI configuration; use `update` to change it.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--manual-time` | whole number, 0 or more | **required** | Manual time a human spends per item, in `--time-unit`. |
| — | `--time-unit` | `Seconds`, `Minutes`, `Hours` | `Minutes` | Unit of `--manual-time`. |
| — | `--volume` | whole number, 0 or more | — | Items processed per `--volume-period`. |
| — | `--volume-period` | `Day`, `Week`, `Month`, `Year` | `Month` when `--volume` is set | Period `--volume` is measured over. Requires `--volume`. |
| — | `--employee-cost` | number, 0 or more, up to 4 decimals | — | Fully loaded cost of the employee doing the work, in USD, over `--cost-period`. |
| — | `--cost-period` | `Annual`, `Hourly` | `Annual` when `--employee-cost` is set | Period `--employee-cost` is expressed over. Requires `--employee-cost`. |
| — | `--cost-per-item` | number, 0 or more, up to 4 decimals | — | Manual cost per item, in USD. When omitted, the Orchestrator UI computes it from the other values. |
| — | `--disabled` | flag | off | Create the configuration with ROI tracking off (the UI's "not applicable"). |

Orchestrator applies upper limits configured on the tenant. By default, the limits are 10,000 for `--manual-time`, 10,000,000 for `--volume` and `--employee-cost`, and 100,000 for `--cost-per-item`.

### Examples

```bash
uip or queue-roi create InvoiceQueue --folder-path Shared --manual-time 12

uip or queue-roi create a1b2c3d4-0000-0000-0000-000000000010 \
    --manual-time 12 --time-unit Minutes \
    --volume 4000 --volume-period Month \
    --employee-cost 65000 --cost-period Annual

uip or queue-roi create a1b2c3d4-0000-0000-0000-000000000010 \
    --manual-time 0 --disabled --output-filter 'Key'
```

### Data shape (--output json)

`Code: "QueueRoiCreated"`, with the same `Data` fields as [`get`](#uip-or-queue-roi-get).

## uip or queue-roi update

Update the ROI configuration of a queue. Values you do not pass keep their current setting. Pass at least one value option, `--enabled`, `--disabled`, or a `--no-*` option. Fails with `ErrorCode: "not_found"` when the queue has no ROI configuration; use `create` first.

### Options

`update` accepts the value options of `create`, all optional and without defaults. When you set `--volume` or `--employee-cost` without a period, the stored period is kept, or the `create` default is used when none is stored. It also accepts:

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--no-volume` | flag | — | Clear the stored volume and its period. |
| — | `--no-employee-cost` | flag | — | Clear the stored employee cost and its period. |
| — | `--no-cost-per-item` | flag | — | Clear the manual cost per item, so the Orchestrator UI computes it again. |
| — | `--enabled` | flag | — | Turn ROI tracking on. Mutually exclusive with `--disabled`. |
| — | `--disabled` | flag | — | Turn ROI tracking off. Mutually exclusive with `--enabled`. |

### Examples

```bash
uip or queue-roi update InvoiceQueue --folder-path Shared --volume 5000

uip or queue-roi update a1b2c3d4-0000-0000-0000-000000000010 \
    --employee-cost 45 --cost-period Hourly --no-cost-per-item

uip or queue-roi update a1b2c3d4-0000-0000-0000-000000000010 \
    --disabled --output-filter 'Enabled'
```

### Data shape (--output json)

`Code: "QueueRoiUpdated"`, with the same `Data` fields as [`get`](#uip-or-queue-roi-get).

## uip or queue-roi delete

Delete the ROI configuration of a queue. Requires `-y, --yes` — the CLI never prompts for destructive operations.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-y` | `--yes` | flag | — | **Required.** Confirms the deletion. |

### Examples

```bash
uip or queue-roi delete a1b2c3d4-0000-0000-0000-000000000010 --yes
```

### Data shape (--output json)

```json
{
  "Code": "QueueRoiDeleted",
  "Data": {
    "QueueKey": "a1b2c3d4-0000-0000-0000-000000000010",
    "QueueName": "InvoiceQueue",
    "Folder": "Shared",
    "Status": "Deleted"
  }
}
```

## Exit codes

Refer to [Exit codes](./exit-codes.md) for the shared contract. Verb-specific behavior:

- `update` exits `3` (`ValidationError`) when no value option is passed.
- `create` and `update` exit `3` when `--volume-period` is passed without `--volume`, when `--cost-period` is passed without `--employee-cost`, or when `--enabled` and `--disabled` are both passed.
- `update` exits `1` with `ErrorCode: "not_found"` when the queue has no ROI configuration.
- `delete` exits `1` if `-y, --yes` is omitted.

## Related commands

- [`uip or queues`](./uip-or-queues.md) — find queue names and keys.
- [`uip or process-roi`](./uip-or-process-roi.md) — the Business ROI configuration of a process.

## See also

- [`uip or` overview](./uip-or.md) — shared conventions for every `uip or` verb.