> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enum Columns

> Enum columns display dropdown fields in the Nextedy RISKSHEET grid. They map to Polarion enumeration custom fields and present a list of predefined options for selection.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Enum Type Syntax

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/yWl5nA2D0IzEnZC1/risksheet/diagrams/reference/columns/enum-columns/diagram-1.svg?fit=max&auto=format&n=yWl5nA2D0IzEnZC1&q=85&s=1bff52944ab39d0f39b03b5bee9692e2" alt="diagram" style={{ maxWidth: "620px", width: "100%" }} width="620" height="340" data-path="risksheet/diagrams/reference/columns/enum-columns/diagram-1.svg" />
</Frame>

The identifier after the colon is the ID of a Polarion enumeration (defined under **Administration > Enumerations**). Risksheet loads the values automatically at runtime.

## Column Type Comparison

| Feature                        | `enum:ID`                               | `rating:ID`                                              | `multiEnum:ID`                                                            |
| ------------------------------ | --------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------- |
| Selection mode                 | Single-select                           | Single-select                                            | Multi-select                                                              |
| Shows descriptions in dropdown | No (unless `showEnumDescription: true`) | Yes                                                      | No (unless `showEnumDescription: true`)                                   |
| Typical Polarion enum value ID | String                                  | Integer                                                  | String                                                                    |
| Typical use case               | Categorical fields                      | Risk assessment scales (severity, occurrence, detection) | Tags, multiple categories                                                 |
| Cell decorator comparison      | Compare against enum value ID           | Compare against integer ID                               | See [Multi-Enum Columns](/risksheet/reference/columns/multi-enum-columns) |

<Tip title="Choosing between enum and rating">
  Use `rating:ID` for risk assessment scales (severity, occurrence, detection) where enum value descriptions should appear inline in the dropdown. Use `enum:ID` for categorical selections where the name alone is sufficient.
</Tip>

## Enum Column Properties

| Name                  | Type      | Default         | Description                                                                                                                                                                                                           |
| --------------------- | --------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | `string`  | Auto-generated  | Unique column identifier                                                                                                                                                                                              |
| `type`                | `string`  | None            | `enum:ENUM_ID`, `rating:ENUM_ID`, or `multiEnum:ENUM_ID` — the ID part references a Polarion enumeration                                                                                                              |
| `header`              | `string`  | None            | Column header display text                                                                                                                                                                                            |
| `bindings`            | `string`  | Same as `id`    | Polarion work item field ID that holds the enum value                                                                                                                                                                 |
| `level`               | `number`  | `1`             | Visual hierarchy level for cell merging (1-indexed). An unleveled risk-item column defaults to level 1 and merges into the first level                                                                                |
| `readOnly`            | `boolean` | `false`         | Controls editability. Optional for main row item columns; **mandatory** for upstream/downstream linked item columns. Since v25.2.0, `readOnly: true` on a title column still allows creation of new work items inline |
| `filterable`          | `boolean` | `true`          | Allows filtering by enum values                                                                                                                                                                                       |
| `showEnumDescription` | `boolean` | `false`         | When `true`, displays the Polarion enum value description next to its ID/name in both the dropdown and the rendered cell (useful for `enum` and `multiEnum` columns where descriptions are not shown by default)      |
| `width`               | `number`  | See application | Column width in pixels                                                                                                                                                                                                |

<Warning title="Type specification for linked item columns">
  The `type: enum:*` property is optional for main row item columns (Risksheet auto-detects from the bound Polarion field). However, it is **mandatory** for all upstream and downstream linked item columns. Omitting the type for linked items results in the column not rendering correctly.
</Warning>

## How Enum Values Are Defined

All enum, rating, and multiEnum values come from **Polarion enumerations** — they are not defined in the sheet configuration.

1. **Define the enumeration in Polarion**: Go to **Administration > Enumerations** and create an enumeration with the values you need. For rating scales, use integer IDs (for example `1`, `4`, `7`, `10`); for categorical enumerations, use string IDs (for example `disc`, `drum`, `regen`). Each value has an ID, a name (displayed in the UI), and an optional description.
2. **Bind a custom field to the enumeration**: In Polarion, define or extend a work item type with a custom field whose type is `Enum:<enumId>` (single-select) or `Enum:<enumId>:multi` (multi-select).
3. **Reference the enumeration from a column**: In the sheet configuration, set `type: enum:<enumId>` (or `rating:<enumId>` / `multiEnum:<enumId>`) and `bindings: <fieldId>` on the column.

The Risksheet server loads the enumeration values automatically — there is no `enums` or `ratings` section in the sheet configuration.

### Example: Category Column

```yaml theme={null}
columns:
  - id: category
    header: Category
    type: enum:risk_category
    bindings: category
    level: 1
    width: 120
```

This column displays the values defined in the Polarion enumeration `risk_category` and stores the user's selection in the custom field `category` on the risk work item.

### Example: Rating Column With Descriptions

```yaml theme={null}
columns:
  - id: severity
    header: Severity
    type: rating:severity_scale
    bindings: severity
    level: 1
    width: 90
```

The Polarion enumeration `severity_scale` would contain entries such as `1 — No effect`, `4 — Moderate`, `7 — High`, `10 — Hazardous`. Because the column type is `rating:*`, Risksheet shows the description next to each value in the dropdown.

### Example: Multi-Select With Descriptions

```yaml theme={null}
columns:
  - id: measures
    header: Measures
    type: multiEnum:measure_types
    bindings: measures
    showEnumDescription: true
    level: 1
    width: 220
```

Setting `showEnumDescription: true` causes the descriptions defined in the Polarion enumeration `measure_types` to be shown alongside each option in the dropdown and inside the rendered cell.

## Cell Decorators for Enum Columns

Cell decorators compare against enum **value IDs**, not display names. This is a common source of errors. For `enum`/`multiEnum` columns this is a string ID, and for `rating` columns it is an integer ID.

```yaml theme={null}
cellDecorators:
  brakeStatus: |
    function(info){
      var val = info.value;
      $(info.cell).toggleClass('approved', val === 'yes');
      $(info.cell).toggleClass('pending', val === 'pending');
    }

styles:
  .approved: '{background-color: #eaf5e9 !important; color: #1d5f20 !important;}'
  .pending: '{background-color: #fff3d2 !important; color: #735602 !important;}'
```

<Warning title="Compare against IDs, not display names">
  Cell decorator functions must compare against the enum value ID (for example `'yes'`), not the display name (for example `'Y'`). Using display names causes the comparison to fail silently. CSS style definitions require `!important` to override Risksheet default styling. Use `$(info.cell).toggleClass(...)` rather than inline style mutations, because Risksheet reuses cells when scrolling.
</Warning>

## Enum Loading and Filtering

Risksheet loads enumeration values automatically for any column whose `type` is `enum:*`, `rating:*`, or `multiEnum:*`. The server resolves the ID after the colon against the Polarion enumerations of the project (or globally, if the enumeration is global).

* **Risk-item enum fields** are filtered by the Polarion enumeration bound to the risk work item type.
* **Task-item enum fields** are filtered by the Polarion enumeration bound to each task work item type, including the multi-project case (`dataTypes.task.projects`).
* **Project pickers** show only projects allowed in the configuration.

Because enums are defined in Polarion and resolved at runtime, the same column configuration works across environments as long as the enumeration ID matches.

## WorkItem Enum Fields

WorkItem enum fields (Polarion custom fields whose enumeration is a query for work items) use a type identifier matching the Polarion XML custom field definition:

```yaml theme={null}
columns:
  - id: workpackage
    type: multiEnum:@NoIDWorkItems[workpackage]
    bindings: workpackage
    header: Work Package
```

<Info title="Verify in application">
  WorkItem enum fields have limited support on upstream and downstream linked item columns compared to main row item columns. Check the Polarion custom field XML definition (`custom-fields.xml`) for the exact enumeration name to use in the `type` property.
</Info>

## Dependent Enumerations

Dependent enumerations restrict the values offered in one enum column based on the value selected in another enum column. **This is a column-level feature, not a top-level section of the sheet configuration.** It was introduced in v25.3.1 for single-value enum columns; multi-value (`multiEnum`) dependency is planned for a future release.

Dependencies are defined on the dependent column using a column-level property that names the controlling column and supplies the value mapping. Verify the exact property name and shape in the configuration editor of your Risksheet version.

| Pattern          | Description                                                           |
| ---------------- | --------------------------------------------------------------------- |
| Tree-based (1:N) | Each value of the source column maps to a unique set of target values |
| Mixed            | The same target value can be shared across multiple source values     |

<Info title="Verify in application">
  Dependent enumeration support landed in v25.3.1 for single-value enums. The v25.5.0 configuration editor provides YAML editing with syntax highlighting and inline error detection, which is the recommended way to author dependency configurations.
</Info>

## PDF Export Behavior

Enum fields in PDF export have inconsistent rendering depending on column type:

| Field Type             | Export Behavior                                    |
| ---------------------- | -------------------------------------------------- |
| Regular `enum` columns | Exported with display names                        |
| `rating` columns       | Exported with numeric IDs instead of display names |
| User reference columns | Exported with user IDs instead of display names    |

<Tip title="Consistent export formatting">
  Use saved views as an alternative export option to control how enum fields are rendered in PDF output. See [Saved Views](/risksheet/reference/saved-views).
</Tip>

## Complete Example

```yaml theme={null}
columns:
  - id: title
    header: Failure Mode
    bindings: title
    type: string
    level: 1
    width: 250
  - id: severity
    header: Severity (S)
    bindings: severity
    type: rating:severity_scale
    level: 1
    width: 80
  - id: occurrence
    header: Occurrence (O)
    bindings: occurrence
    type: rating:occurrence_scale
    level: 1
    width: 80
  - id: detection
    header: Detection (D)
    bindings: detection
    type: rating:detection_scale
    level: 1
    width: 80
  - id: category
    header: Category
    bindings: category
    type: enum:risk_category
    level: 1
    width: 120
  - id: measures
    header: Measures
    bindings: measures
    type: multiEnum:measure_types
    showEnumDescription: true
    level: 1
    width: 180

cellDecorators:
  category: |
    function(info){
      var val = info.value;
      $(info.cell).toggleClass('catDesign', val === 'design');
      $(info.cell).toggleClass('catProcess', val === 'process');
    }

styles:
  .catDesign: '{background-color: #e3f2fd !important; color: #1565c0 !important;}'
  .catProcess: '{background-color: #fff3e0 !important; color: #e65100 !important;}'
```

The values `design`, `process`, and the entries of `severity_scale`, `occurrence_scale`, `detection_scale`, `risk_category`, and `measure_types` are defined as Polarion enumerations under **Administration > Enumerations**; the sheet configuration only references them by ID.

## See Also

* [Multi-Enum Columns](/risksheet/reference/columns/multi-enum-columns) — Multi-select enum configuration
* [Column Type Reference](/risksheet/reference/columns/column-types) — Complete column type listing
* [Cell Decorators](/risksheet/reference/styling/cell-decorators) — Conditional formatting with enum values
* [Conditional Formatting](/risksheet/reference/styling/conditional-formatting) — Style-based formatting rules
* [Configuration Properties Index](/risksheet/reference/configuration/properties-index) — Complete property reference

<LastReviewed date="2026-06-24" />