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

# Multi-Enum Columns

> Multi-enum columns allow users to select multiple enumeration values for a single cell in the Nextedy RISKSHEET grid.

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>;
};

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

## Column Type Syntax

| Syntax               | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| `multiEnum:<enumId>` | Multi-select dropdown using the specified Polarion enumeration |

The `<enumId>` portion must match an enumeration ID defined in Polarion Administration. The Risksheet server loads the enum values from Polarion at runtime — there is no enum definition in the sheet configuration.

<Warning title="Common Mistake: Using `enum:` Instead of `multiEnum:`">
  Setting `type: enum:<enumId>` on a multi-select Polarion field renders a **single-select** dropdown. You must use `type: multiEnum:<enumId>` to enable multi-value selection, even if the underlying Polarion field supports multiple values. This is the most common multi-enum configuration error.
</Warning>

## Column Properties

| Name           | Type      | Default                               | Description                                                                  |
| -------------- | --------- | ------------------------------------- | ---------------------------------------------------------------------------- |
| `id`           | `string`  | Auto-generated from header or binding | Unique identifier for the column                                             |
| `type`         | `string`  | Auto-detected from binding            | Must be `multiEnum:<enumId>` for multi-select behavior                       |
| `header`       | `string`  | None                                  | Display text in the column header                                            |
| `bindings`     | `string`  | Same as `id`                          | The Polarion field ID this column maps to                                    |
| `readOnly`     | `boolean` | `false`                               | Controls whether the column cells can be edited                              |
| `filterable`   | `boolean` | `true`                                | Controls whether users can filter by values in this column                   |
| `width`        | `number`  | See application                       | Column width in pixels                                                       |
| `minWidth`     | `number`  | See application                       | Minimum resize width in pixels                                               |
| `level`        | `number`  | `1`                                   | Visual hierarchy level for cell merging (not set for task columns)           |
| `headerGroup`  | `string`  | None                                  | Header group this column belongs to for multi-level headers                  |
| `collapseTo`   | `boolean` | `false`                               | When `true`, this column remains visible when its header group is collapsed  |
| `cellCss`      | `string`  | None                                  | CSS class name(s) to apply to cells in this column                           |
| `cellRenderer` | `string`  | None                                  | Name of a function in the `cellDecorators` section for custom cell rendering |
| `format`       | `string`  | None                                  | Display format string for the column data                                    |

<Note title="Text Wrapping">
  Multi-enum cell text wrapping is controlled through CSS rules defined in the sheet configuration's `styles` section (and applied via `cellCss`), not through a column-level property.
</Note>

## Enumeration Source

Enumerations referenced by `multiEnum:<enumId>` columns are defined in **Polarion Administration > Enumerations** — not in the sheet configuration file. The Risksheet server loads enum values (option ID, display name, optional description, optional icon) from Polarion when the document opens.

To make values available in a multi-enum column:

1. Create or edit the enumeration in Polarion Administration. Each option has an `id` (stored value) and a display `name`.
2. Bind a Polarion custom field (or work item field) to that enumeration. The custom field must be configured to accept multiple values for native multi-enum storage.
3. In the sheet configuration, reference the field via `bindings` and set `type: multiEnum:<enumId>` using the enumeration ID from step 1.

<Note title="Enum IDs vs. Display Names">
  Cell decorators, formulas, and filter comparisons always work with enum **IDs**, not display names. For example, if an option displays as "High" but has `id: high`, use `'high'` in your decorator or formula logic.
</Note>

### Enum Option Fields (loaded from Polarion)

| Field         | Description                                                                                                                 |
| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id`          | Internal identifier used for storage, comparison, and cell decorator logic. This is the value stored in the Polarion field. |
| `name`        | Display label shown in the dropdown picker and rendered in the cell.                                                        |
| `description` | Extended description text (shown in `rating:<enumId>` columns; not displayed in standard `enum:` or `multiEnum:` columns).  |
| `icon`        | Icon identifier for visual display alongside the option (when configured in Polarion).                                      |

## Data Storage

Multi-enum columns support two Polarion storage formats:

| Storage Type           | Format                       | Description                                                                 |
| ---------------------- | ---------------------------- | --------------------------------------------------------------------------- |
| Native multi-enum      | Polarion `List<IEnumOption>` | Native Polarion multi-select custom fields containing `IEnumOption` objects |
| Comma-separated string | `"val1,val2,val3"`           | String fields containing comma-separated enum IDs                           |

Blank options are automatically filtered out from the stored values during data processing. Risksheet handles bidirectional conversion between the grid display format (array of enum IDs) and the Polarion storage format transparently — all data continues to live in Polarion work items, not in a separate Risksheet store.

## Rendering Behavior

Multi-enum values render as a list of styled tags within the cell:

* Each selected value appears as an individual `span.multi-enum-item` element
* All items are wrapped in a `span.multi-enum-list` container
* Tags display the `name` property from the Polarion enumeration
* If an enum option ID is not found in the loaded enumeration, the raw ID value is displayed as a fallback
* Values stored as arrays are processed during cell rendering to resolve IDs to display labels

## Filtering Behavior

Multi-enum columns support two filter modes with significantly different behavior:

| Filter Mode                             | Behavior                                                                             | Use Case                                                                                                          |
| --------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **Filter by Value**                     | Matches exact combinations of selected values                                        | Finding rows with a specific set of selections (e.g., exactly "Safety" and "Regulatory" with no other selections) |
| **Filter by Condition** with `Contains` | Finds all rows where the specified value is included, regardless of other selections | Finding all rows that include "Safety" among their selections, regardless of what else is selected                |

<Tip title="Filtering by a Single Value">
  Use **Filter by Condition** with the **Contains** option to find all rows that include a specific enum value. **Filter by Value** requires selecting all exact combinations containing that value, which is impractical for fields with many options. This is the most common filtering question from users working with multi-enum columns.
</Tip>

## Cell Merging

Multi-enum values participate in the hierarchical merging system. Cells with identical selections merge vertically when they are in the same visual level group:

* Multi-enum values are converted to string representations for merge comparison
* Cells with identical value arrays (same selected options in the same order) merge properly
* Empty brackets `[]` or invalid JSON prevent merging
* The values must be in identical order for cells to merge

## Export Behavior

### Excel Export

When exporting to Excel, multi-enum columns are converted to a comma-separated list of human-readable option names:

* Internal enum IDs are resolved to display names from the Polarion enumeration
* Values are separated by comma and newline characters
* Unknown enum IDs (not found in the loaded enumeration) are preserved as-is in the export

### PDF Export

PDF export renders multi-enum values as comma-separated text of resolved enum labels, consistent with the Excel export format.

## WorkItem Enum Fields

For custom fields that are enumerations of WorkItem type, the `type` value must match the XML custom field configuration exactly:

```yaml theme={null}
columns:
  - id: wiAllocation
    header: Allocation
    type: multiEnum:@NoIDWorkItems[workpackage]
    bindings: wit_measure-en_me_allocation
```

<Info title="Verify in application">
  WorkItem enum fields require specific type syntax matching the XML custom field definition in Polarion. The exact format depends on your project's custom field configuration. Check `.polarion/documents/fields/custom-fields.xml` for the correct type string. Upstream and downstream WorkItem enum fields have more limited support compared to row item properties.
</Info>

## Dependent Multi-Enum Options

Multi-enum columns support dependent option filtering based on a parent enum value. Dependent enumerations are a **column-level feature** (v25.3.1+ for single-value, v25.4.0+ for multi-value) — they are configured through column properties and the underlying Polarion enumeration relationships, not through a top-level configuration section.

When the parent column value changes, the multi-enum dropdown dynamically refreshes its available options based on the relationships defined between the parent and child enumerations in Polarion.

<Note title="Version Information">
  Dependent enumeration support for multi-value enums was added in version 25.4.0. Single-value dependent enums were introduced in version 25.3.1. Ensure your Risksheet version supports the dependent enum feature before configuring dependent enum columns.
</Note>

## Undo/Redo Support

Multi-enum fields have specialized undo logic. When you undo changes to a multi-enum column, the system restores visible options from stored enum item IDs. Dependent column values are also automatically restored to maintain data consistency.

## Version History

| Version | Change                                                                                                                                                          |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 24.2.0  | Fix for `multiEnum` type column behavior                                                                                                                        |
| 24.6.0  | Fixed `multiEnum` display at minimal row height; fixed cross-project downstream item linking (previously required removing `task.project` column as workaround) |
| 25.3.1  | Dependent enum support for single-value enums                                                                                                                   |
| 25.4.0  | Dependent enum support for multi-value enums                                                                                                                    |

## Error Messages

| Error                       | Cause                                                                                                        | Resolution                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| "Error while loading enums" | The `type` property references an enum ID that does not exist in Polarion Administration or cannot be loaded | Verify that the enum ID in the `type` property matches an enumeration defined in **Administration > Enumerations** |

## Complete Example

An FMEA sheet configuration with multi-enum columns for impact categories and affected systems. The referenced enumerations (`impactCategoryEnum`, `affectedSystemEnum`, and the rating scales) are defined in Polarion Administration:

```yaml theme={null}
columns:
  - id: systemItemId
    header: ID
    width: 80
    readOnly: true

  - id: title
    header: Failure Mode
    width: 200

  - id: impactCategories
    bindings: customField_impactCategories
    header: Impact Categories
    type: multiEnum:impactCategoryEnum
    width: 180
    filterable: true
    level: 1

  - id: affectedSystems
    bindings: customField_affectedSystems
    header: Affected Systems
    type: multiEnum:affectedSystemEnum
    width: 200
    filterable: true
    level: 1

  - id: sev
    bindings: customField_severity
    header: S
    type: rating:severityRating
    width: 50

  - id: occ
    bindings: customField_occurrence
    header: O
    type: rating:occurrenceRating
    width: 50

  - id: det
    bindings: customField_detection
    header: D
    type: rating:detectionRating
    width: 50

  - id: rpn
    header: RPN
    formula: commonRpn
    width: 60
    cellRenderer: rpn

formulas:
  commonRpn: "function(info){ var value = info.item['occ']*info.item['det']*info.item['sev']; return value?value:null; }"

cellDecorators:
  rpn: "function(info){ var val = info.value; $(info.cell).toggleClass('rpn1', val>0 && val<=150); $(info.cell).toggleClass('rpn2', val>150 && val<=250); $(info.cell).toggleClass('rpn3', val>250); }"

styles:
  ".rpn1": "{background-color: #eaf5e9 !important; color: #1d5f20 !important;}"
  ".rpn2": "{background-color: #fff3d2 !important; color: #735602 !important;}"
  ".rpn3": "{background-color: #f8eae7 !important; color: #ab1c00 !important;}"
```

The enumeration IDs (`impactCategoryEnum`, `affectedSystemEnum`, `severityRating`, `occurrenceRating`, `detectionRating`) must exist in **Polarion Administration > Enumerations**, and the custom fields (`customField_impactCategories`, `customField_affectedSystems`, etc.) must be bound to those enumerations on the work item type.

## Related Pages

* [Enum Columns](/risksheet/reference/columns/enum-columns) — Single-select enumeration columns
* [Column Type Reference](/risksheet/reference/columns/column-types) — Overview of all column types
* [Data Types](/risksheet/reference/columns/data-types) — Work item type configuration
* [Cell Decorators](/risksheet/reference/styling/cell-decorators) — Conditional formatting with decorators
* [Conditional Formatting](/risksheet/reference/styling/conditional-formatting) — All formatting approaches
* [Sheet Configuration Format](/risksheet/reference/configuration/risksheet-json-format) — Complete sheet configuration reference

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