# Aux reason codes

> Manage the aux reason catalogue: shrinkage buckets, system-only codes, legacy slots, sort order, and deactivation that preserves history.

The **Aux reasons** admin screen edits your organisation's aux reason
catalogue — the `dim_aux_reason` dimension. Each row is one reason an
agent can be in AUX (not-ready) state: break, lunch, training, and so
on. The catalogue drives two things at once: the AUX-state dropdown the
agent sees, and the shrinkage bucket the reason rolls up into for
reporting.

The CSTA agent-state model treats `auxReason` as a free-form,
reporting-only label. This page covers the catalogue behind that label
inside TeleQuick: what each column means, which codes an agent may
select, and what happens to reports when you retire a code.

## What an aux reason is and where it appears

An aux reason row has these fields:

| Field              | Type                                     | Notes                                                              |
| ------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
| `code`             | string, up to 40 chars                   | Stable machine identifier. The form lowercases input and replaces whitespace runs with `_`, so `Team Meeting` becomes `team_meeting`. |
| `name`             | string, up to 120 chars                  | Display name shown to agents and in reports.                       |
| `shrinkage_bucket` | `planned` / `unplanned` / `off_phone`    | Reporting roll-up. Defaults to `unplanned` on a new row.            |
| `legacy_slot`      | integer 0–9, or empty                    | Optional numeric slot. Empty renders as `—`.                        |
| `system_only`      | boolean                                  | When set, the runtime picks the reason; the agent cannot.           |
| `sort_order`       | integer 0–9999                           | Position in the agent's dropdown. Defaults to `100` on a new row.   |
| `active`           | boolean                                  | Whether the code is selectable. New codes are created active.       |

The list view shows sort order, code, name, bucket, legacy slot, the
system lock, status, and tags. Clicking any row opens the edit drawer.

Aux reasons are also a taggable resource kind (`dim_aux_reason`), so you
can attach tags from the list without opening the drawer.

## Shrinkage buckets: planned, unplanned, off phone

Every reason must belong to exactly one of three buckets. The bucket is
what workforce reports aggregate on, so pick it from the perspective of
the schedule rather than the agent:

| Bucket       | Meaning in reporting                                                   |
| ------------ | ---------------------------------------------------------------------- |
| `planned`    | Time away from the phone that the schedule already accounts for.       |
| `unplanned`  | Time away that the schedule did not account for.                       |
| `off_phone`  | Time the agent is working but not available for contacts.              |

Because the bucket lives on the reason and not on the individual state
change, changing a reason's bucket changes how existing timeline records
roll up the next time a report is run. If you need the old and new
classification to coexist, create a second code with the new bucket and
deactivate the old one instead of re-bucketing in place.

## System-only codes versus agent-selectable codes

The **System-only** toggle controls who may put an agent into the
reason:

- **Off (default)** — the reason appears in the agent's AUX dropdown and
  the agent can select it.
- **On** — the runtime sets the reason; the agent cannot pick it. The
  list marks these rows with a **Locked** chip.

Use system-only for reasons that describe something the platform
observed rather than something the agent chose. Keep them in the
catalogue anyway: reports need a name and a shrinkage bucket for those
intervals just as much as for agent-selected ones.

System-only is an editable flag on any row, including rows that shipped
with the organisation, so you can promote a reason out of the agent's
dropdown without deleting it.

## Legacy slots and numeric selection

`legacy_slot` holds a single digit, 0 through 9, and is optional. It
exists for integrations and endpoints that identify an aux reason by a
numeric slot rather than by code — a deskphone-style single-digit
selection. Rows with a slot show as `#3` in the **Legacy** column; rows
without one show `—`.

Leave the field empty unless something downstream actually needs the
digit. The drawer does not pre-fill a slot, and only ten are available,
so the digits are worth reserving for the reasons your endpoints
reference. If the server rejects a slot — for example because another
reason already holds it — the message appears in the red banner at the
top of the drawer and the save does not go through.

## Sort order

`sort_order` is a plain integer from 0 to 9999 and determines the order
of the AUX dropdown the agent sees. The list is sorted by it, with the
value shown in the first column, so the table reads in the same order
the agent will see.

New rows default to `100`. Leaving gaps between values (100, 200, 300)
lets you insert a reason later without renumbering the whole catalogue.

## Deactivating a code without breaking history

The drawer's **Deactivate** action calls the remove procedure, which
does not erase the row. The confirmation states it plainly:
deactivated, not erased — historical timeline records still reference
it. This is why the catalogue has an `active` flag rather than a delete:

- An inactive reason stops being selectable going forward.
- Past agent-state intervals keep pointing at the same row, so reports
  over historical windows still resolve the code to its name and its
  shrinkage bucket.

Two consequences are worth planning for:

- **Live agents.** An agent already sitting in a reason you deactivate
  is not retroactively moved. Deactivation affects new selections, not
  intervals already open. Prefer deactivating during a quiet window and
  telling supervisors which replacement code to use.
- **Reversal.** Deactivation is not permanent. Open the row from the
  list with **Include inactive** checked and turn the **Active** toggle
  back on. The toggle is only present in edit mode — creation always
  produces an active code.

Because the row survives, do not reuse a retired `code` string for an
unrelated reason. Historical records would then mix two meanings under
one label.

## Defaults a new organisation starts with

A new organisation is seeded with a default set of aux reasons, so the
agent's AUX dropdown is usable before an administrator touches this
screen. The empty state on this screen says so: new orgs get a default
set, and you can add your own.

Seeded rows are ordinary catalogue rows. You can rename them, re-bucket
them, change their sort order, mark them system-only, or deactivate
them, subject to the same rules as rows you create yourself. If the
screen is genuinely empty — every seeded row deactivated, or a tenant
provisioned without them — the empty state offers **Create first
reason**.

## Finding a code

The filter bar above the table has two controls:

- **Search** matches on code or name. It filters server-side and resets
  to the first page as you type.
- **Include inactive** adds deactivated rows to the result. Leave it off
  for the working catalogue; turn it on to audit retired codes or to
  reactivate one.

Results are paginated at 50 rows per page, and the header shows the
total count of codes matching the current filters.

## Related

- [Telephony metrics](/glossary/metrics) — where shrinkage sits among the contact-centre numbers
- [Telemetry](/platform/telemetry) — the operational streams that carry agent and call data