> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cxp.crescendo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Dimensions

> Define and validate reusable conversation classifications, then use them in Drilldown reports, Search, and Views.

Custom Dimensions turn existing conversation data into a reusable classification
or calculated value. Define the logic once, then use the dimension in filters,
report rows, and report columns.

For example, a **Support Segment** dimension can classify conversations as VIP,
Returning, or Standard based on their tags. A numeric dimension could emit a
count; a boolean dimension could indicate whether a condition is true.

A dimension calculates its value when queried. It does not write a new tag or
editable field onto the conversation. Use
[custom fields](https://docs.cxp.crescendo.ai/admin/statuses-tags-and-custom-fields.md#custom-fields) when you
need agents to enter and maintain a value themselves.

**Elapsed HT** is already available as a built-in calculated value. Use it in
Search or View filters and Drilldown rows or columns without creating, validating,
or saving a dimension definition. It measures agent handling responsibility at
a fixed query cutoff and returns zero when progress is unavailable. See
[Elapsed HT](https://docs.cxp.crescendo.ai/capabilities/searching-conversations.md#elapsed-ht) for its meaning and limits, or
[group a Drilldown report by it](https://docs.cxp.crescendo.ai/capabilities/drilldown-reports.md#choose-rows-and-columns).

## Before you start

* You need Owner or Administrator access to create, generate, validate, change,
  import, or delete definitions.
* Your organization needs indexed conversations to produce a meaningful sample.
* Readers can use saved dimensions through the filters and reports their role
  already permits.

Definitions are shared with the legacy application. Editing a dimension affects
reports and filters that reference that definition in either application.

## Example: classify support segments

The screenshots use synthetic conversations with `vip` and `repeat-customer`
tags. The intended classification is:

| Conversation tags | Result | Why |
| - | - | - |
| `vip` | VIP | VIP has first priority. |
| `vip`, `repeat-customer` | VIP | A conversation belongs to one segment in this example. |
| `repeat-customer`, without `vip` | Returning | It matches the second rule. |
| Other tags, or no tags | Standard | The fallback covers all remaining conversations. |

In the six-conversation report sample, these rules produce **two VIP**, **two
Returning**, and **two Standard** conversations. The `docs-handle-time` tag
identifies that sample; it is not part of the segment rules. The editor images
illustrate the same rules using an earlier, separate demonstration definition.

### 1. Add the name and description

Open **Settings → Custom Dimensions**, then select **New Dimension**.
In the **Dimension** tab, enter:

| Field | Example | Guidance |
| - | - | - |
| **Title** | Support Segment | The readable name people choose in filters and reports. |
| **Field Name** | `docs_handle_time_segment` | Start with a letter; use letters, numbers, and underscores. Choose a unique name that does not replace an existing conversation field or dimension. |
| **Description** | The rules below | State precedence and what happens with missing or unmatched values. |

Copy this description and adapt its tag names to your organization:

```text theme={null}
Classify conversations tagged vip as VIP.
Otherwise, classify conversations tagged repeat-customer as Returning.
Classify all other conversations, including those without tags, as Standard.
VIP takes precedence when both tags are present.
```

### 2. Apply and validate

Select **Apply** inside the bottom-right corner of Description. CXP generates
the type and script, then automatically runs validation. The six-line Description
area can be resized vertically if you need more room.

**Save** stays disabled until the current definition passes validation. When
validation is required, **Validate** is the highlighted action. You can run it
again without regenerating the script.

![Support Segment Dimension tab with title, field name, classification description, Apply and validation results](https://mintcdn.com/cxp/dLZXah_wJs6ZUvfY/assets/screenshots/custom-dimension-editor-demo.png?fit=max\&auto=format\&n=dLZXah_wJs6ZUvfY\&q=85\&s=8df60ae28942e539fcedc9c6f23015e0)

Describe the classification, apply it, and review the validation sample before saving.

Validation evaluates up to 100 recent production conversations and displays the
sample size, missing count, and comma-separated value counts. It shows up to
20 distinct preview values and notes when more values are omitted.

> [!NOTE]
>
> Validation uses recent conversations across the organization, not a particular
> report's filters. The earlier editor screenshot shows a Standard-only validation
> sample. The separate six-conversation report example below includes all three
> segments. Successful validation confirms execution on the sample; inspect a
> filtered report to check the classification across your intended population.

### 3. Inspect or edit the script

Open **Advanced** to inspect the generated type and Painless script. The script
editor provides syntax highlighting and at least ten lines of space.

The following keyword script implements the example's ordered rules:

```java theme={null}
if (doc.containsKey('state.tags') &&
    doc['state.tags'].contains('vip')) {
  emit('VIP');
} else if (doc.containsKey('state.tags') &&
           doc['state.tags'].contains('repeat-customer')) {
  emit('Returning');
} else {
  emit('Standard');
}
```

This example uses indexed conversation tags. Other source properties need logic
suited to their data type and availability. Review generated logic before relying
on it for a business decision.

![Advanced tab with the Support Segment Painless script, type selector and validation preview](https://mintcdn.com/cxp/dLZXah_wJs6ZUvfY/assets/screenshots/custom-dimension-script-demo.png?fit=max\&auto=format\&n=dLZXah_wJs6ZUvfY\&q=85\&s=d865644adb3183a3e600c5de57f479cd)

Advanced exposes the keyword type and the script implementing the segment rules.

Any edit invalidates the previous validation result, including a manual script
edit. **Save** becomes disabled and **Validate** becomes primary again. Select
**Validate**; fix errors and repeat until it succeeds, then select **Save**.
Saving also validates the definition on the server.

Failed generation or validation keeps Save disabled. If the sample contains no
conversations, it cannot establish how the script behaves on real records.

## Use the dimension in a Drilldown report

Open a [Drilldown report](https://docs.cxp.crescendo.ai/capabilities/drilldown-reports.md) and select Support Segment in
**Group By**. Choose Status in **Split By**. To reproduce the example, add Tags
`docs-handle-time` and select the date range covering the synthetic conversations.

![Support Segment report with two VIP, two Returning, and two Standard conversations, split by status](https://mintcdn.com/cxp/sTvyAxtCMQDKa5Vp/assets/screenshots/drilldown-custom-dimension-demo.png?fit=max\&auto=format\&n=sTvyAxtCMQDKa5Vp\&q=85\&s=9d685ce416c349f11530f5b96e9293ed)

The same six conversations classified into three equal segments and compared by status.

You can also keep Category as the row grouping and select Support Segment in
**Split By**, or filter the report to just VIP conversations. Custom dimensions
appear alongside standard properties in all three controls.

Select VIP's main count to open its two conversations in Search. Select VIP's
Resolved count to add the Resolved status condition; both conversations match
in this example. Counts depend on the report's current filters and source data.

## Use the dimension in Search and Views

In Search, a View editor, or a Drilldown report, select **Filter → Custom
Dimensions**, then select Support Segment. Choose the desired value and apply
the filter. Include or exclude values, or test whether a value is missing or
present. Numeric and date dimensions also support comparison/range controls.

A report count opens the same editable controls automatically:

![Search with the docs-handle-time tag, Support Segment VIP, and Resolved status filters, showing two conversations](https://mintcdn.com/cxp/sTvyAxtCMQDKa5Vp/assets/screenshots/custom-dimension-search-demo.png?fit=max\&auto=format\&n=sTvyAxtCMQDKa5Vp\&q=85\&s=2d099353b786dea31c70fcb293ed8e76)

The VIP/Resolved count opens two conversations in Search with the custom-dimension filter visible and editable.

Select **Save as View** when you have personal View management permission.
The View retains the dimension criteria; you do not need to copy its script.
You can also add dimensions to filters while editing an existing permitted View.

### Combine conditions correctly

Separate filter chips use **AND**. Multiple values inside a single **Any of**
condition use **OR**.

* Support Segment **Any of VIP, Returning** includes either segment.
* Support Segment **VIP** plus Status **Open** includes only open VIP work.
* Two separate conditions on a multi-valued dimension require both values.

The example dimension emits exactly one segment. Two separate chips requiring
VIP AND Returning therefore match nothing. A dimension designed to emit several
labels can legitimately satisfy two separate conditions at once.

## Choose the right output type

| Type | Use for | Example output |
| - | - | - |
| **keyword** | Labels and classifications. | `VIP`, `Returning` |
| **long** | Whole-number values. | `3` |
| **double** | Decimal values. | `2.5` |
| **boolean** | True/false conditions. | `false` |
| **date** | Date/time values emitted by the script. | A valid date value for the configured runtime field |
| **ip** | IP addresses. | `192.0.2.10` |

A script may emit one value, several values, or none. Emitting nothing means
missing. An empty keyword string, numeric zero, and boolean false are actual
values, not missing values. Multi-valued classifications can place one
conversation in multiple report groups or split columns.

Created and Updated are the report's calendar split properties. Custom date
dimensions use exact values; they do not add Day/Week/Month calendar controls.

## Manage definitions

The Custom Dimensions directory supports search, refresh, editing, row export,
row deletion, and selected-row bulk deletion.

| Action | What happens |
| - | - |
| **Edit** | Opens the saved definition. Validate the current draft before saving. |
| **Export** | Downloads one dimension definition as JSON, including its script. |
| **Import** | Opens a new definition for review. Choose a unique field name, validate, and save. It does not silently overwrite an existing definition. |
| **Delete** | Removes the shared definition after confirmation. Existing report and filter references need repair. |

An older report link or paged Search detects a changed definition and asks you to
refresh rather than silently changing the meaning of the query. Refresh the
report and open a new count link after changing a definition. If someone else
edits the definition while your dialog is open, reload before saving over it.

## Troubleshooting

| Problem | Next step |
| - | - |
| Field name is rejected | Start with a letter, use only letters/numbers/underscores, and choose a name that does not collide with an existing field or dimension. |
| Apply fails | Retry with explicit rules and a fallback, or edit the script manually and use Validate. |
| Script fails validation | Review the type, property names, missing-value handling, and emitted values in Advanced. |
| Save is disabled | Validate the current draft. Any edit or failed generation/validation clears the previous success. |
| Preview shows only one value | The recent sample may contain only that value. Check a report with dates and filters covering known examples of each rule. |
| Missing values appear unexpectedly | Check whether every intended branch emits a value and whether source properties exist. |
| An existing report stops working | Check for an edited or deleted dimension; refresh or replace the affected filter/group/split. |

A single query supports at most 16 active custom dimensions. Keep scripts focused
and narrow the conversation population for large reports. Validation is a sample,
not a guarantee that every historical record matches your intended business rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.