Custom Dimensions

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 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 for its meaning and limits, or group a Drilldown report by it.

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:

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 — 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.

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:

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 — 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 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 — 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 — 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.

Explore capabilities

Conversations

Agent availability

Work with external contacts

Concierge Agents

Analyze support

Customer self-service

Before you start