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

# Field Mapping

> Nextedy RISKSHEET maps columns in the grid to Polarion work item fields through a binding system.

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

| Column Definition                        | Binding System                      | Polarion Work Item               |
| ---------------------------------------- | ----------------------------------- | -------------------------------- |
| `bindings: sev`, `type: rating:severity` | Direct field binding                | `sev` (enum-backed custom field) |
| `bindings: req`, `type: itemLink`        | Linked item resolution (upstream)   | Linked work item title           |
| `bindings: task.status`                  | Task prefix resolution (downstream) | Task work item status            |

## Bindings Property

The `bindings` property on a column definition specifies which Polarion work item field the column reads from and writes to. This is the fundamental mapping mechanism in Risksheet.

| Property   | Type   | Default             | Description                                                                                                                    |
| ---------- | ------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `bindings` | string | Same as column `id` | The Polarion work item field name. Supports direct field names, dot notation for linked item properties, and special prefixes. |

```yaml theme={null}
columns:
  - id: severity
    bindings: sev
    header: Severity (S)
    type: rating:severity
```

<Tip title="Bindings vs. ID">
  The `bindings` value determines which Polarion field is read and written. The `id` is the column's unique identifier used for referencing in formulas, cell decorators, views, and `sortBy`. When `bindings` is omitted, it defaults to the same value as `id`.
</Tip>

## Direct Field Binding

The simplest pattern maps a column directly to a Polarion work item field by name. The field name must match the Polarion custom field ID exactly.

| Binding Pattern | Example       | Resolves To                                |
| --------------- | ------------- | ------------------------------------------ |
| `fieldName`     | `sev`         | The `sev` custom field on the risk item    |
| `title`         | `title`       | The work item title (standard field)       |
| `description`   | `description` | The work item description (standard field) |
| `status`        | `status`      | The workflow status (read-only)            |
| `id`            | `id`          | The work item ID (read-only)               |

```yaml theme={null}
columns:
  - bindings: title
    header: Failure Mode
    type: text
  - bindings: sev
    header: Severity
    type: rating:severity
  - bindings: occ
    header: Occurrence
    type: rating:occurrence
  - bindings: description
    header: Description
    type: text
```

## Type Detection from Bindings

When the `type` property is omitted from a column definition, Risksheet queries the Polarion field definition for the bound field and infers the column type automatically.

| Polarion Field Type | Inferred Column Type |
| ------------------- | -------------------- |
| String              | `text`               |
| Integer             | `int`                |
| Float               | `float`              |
| Date                | `date`               |
| Boolean             | `boolean`            |
| Enum (single)       | `enum`               |
| Enum (multi-select) | `multiEnum`          |
| Currency            | `currency`           |
| DurationTime        | `duration`           |

This means you can define columns with just `bindings` and `header`:

```yaml theme={null}
columns:
  - bindings: dueDate
    header: Due Date
```

Risksheet detects that `dueDate` is a Date field in Polarion and automatically sets the column type to `date`.

<Note title="Type Override">
  You can override the auto-detected type by explicitly setting the `type` property. This allows displaying a field differently from its native Polarion type — for example, showing an integer field as a rating dropdown, or a string field as a date.
</Note>

## Enumeration and Rating Bindings

Rating scales and enumerations in Risksheet are **not** defined inside the sheet configuration. They are managed through standard Polarion enumerations:

1. **Define the enumeration in Polarion** — Open **Administration > Enumerations** and create the enumeration with its option IDs and display names (for example, `severity` with options `1`–`5`).
2. **Bind a custom field to the enumeration** — On the risk work item type, create a custom field (for example, `sev`) whose data type references the Polarion enumeration.
3. **Reference the enumeration in the column** — In the sheet configuration, set `type: rating:<enumId>` or `type: enum:<enumId>` and set `bindings:` to the custom field ID. The server loads the enumeration values automatically at runtime.

```yaml theme={null}
columns:
  - id: severity
    bindings: sev
    header: Severity (S)
    type: rating:severity
  - id: riskCategory
    bindings: riskCategory
    header: Risk Category
    type: enum:riskCategory
```

| Field Type           | Display Behavior                           |
| -------------------- | ------------------------------------------ |
| Standard enum fields | Shows enum option **ID** in the grid       |
| `status` field       | Shows enum option **name** (display label) |
| String backing enum  | String value mapped to enum definition     |
| Integer backing enum | Integer value mapped to enum definition    |

<Warning title="Status Field Exception">
  The `status` field is the only enum field that displays its human-readable name rather than its ID. All other enum fields display the option ID in the grid. This is a platform behavior that cannot be overridden.
</Warning>

For multi-select enumerations, use `type: multiEnum:<enumId>`. See [Enum Columns](/risksheet/reference/columns/enum-columns) for the complete enum column reference.

## Linked Item Bindings (Upstream)

For `itemLink` and `multiItemLink` column types, the binding resolves to a linked work item rather than a field on the current row item. This enables upstream traceability columns that display properties of linked requirements, design elements, or other work items.

| Property    | Type    | Default  | Description                                              |
| ----------- | ------- | -------- | -------------------------------------------------------- |
| `bindings`  | string  | Required | The link role name or linked item field identifier.      |
| `type`      | string  | Required | Must be `itemLink` or `multiItemLink`.                   |
| `canCreate` | boolean | `true`   | Whether users can create new linked items from the cell. |

```yaml theme={null}
columns:
  - id: requirement
    bindings: requirement
    header: Linked Requirement
    type: itemLink
    canCreate: false
    width: 200
```

### Linked Field Access

Columns can also display a specific field from the linked item using dot notation in `bindings`:

| Pattern              | Example                | Description                                                    |
| -------------------- | ---------------------- | -------------------------------------------------------------- |
| `linkedItem.fieldId` | `bindings: harm.title` | Field on a linked item (read-only display)                     |
| `linkedItem.$item`   | `bindings: task.$item` | Entire linked item object (for `serverRender` Velocity access) |

See [Item Link Columns](/risksheet/reference/columns/item-link-columns) and [Multi-Item Link Columns](/risksheet/reference/columns/multi-item-link-columns) for detailed configuration.

## Task Bindings (Downstream)

Downstream task columns display properties of mitigation or control action items linked to the current risk item. Task bindings are configured through the `dataTypes.task` section and referenced by task-level columns in the grid.

| Configuration               | Purpose                                                    |
| --------------------------- | ---------------------------------------------------------- |
| `dataTypes.task.type`       | Work item type for tasks (for example, `mitigationAction`) |
| `dataTypes.task.role`       | Link role connecting risk items to tasks                   |
| `dataTypes.task.name`       | Display name in toolbar and menus                          |
| `dataTypes.task.zoomColumn` | Column to focus on after task creation                     |
| `dataTypes.task.document`   | Restrict tasks to a specific LiveDoc path                  |

```yaml theme={null}
dataTypes:
  task:
    type: mitigationAction
    role: mitigates
    name: Mitigation
    zoomColumn: taskTitle
```

Task-level columns do not have the `level` property set (they exist at the task level below the configured hierarchical levels).

See [Task Link Columns](/risksheet/reference/columns/task-link-columns) for task column configuration details.

## Dependent Enumerations (Column-Level)

Risksheet supports cascading relationships between enum columns as a column-level feature (v25.3.1+). When a parent enum value changes, related child enum values are automatically filtered. Dependent enumerations are configured on the individual column definitions, not as a top-level configuration section.

Key behaviors of dependent enum relationships:

* **Forward propagation**: Changing a parent value filters valid child options
* **Backward propagation**: Selecting a child value can auto-populate the parent if only one valid parent exists
* **Multi-select handling**: When a parent enum value is deselected, dependent child values are automatically removed
* **Bulk edit**: Relationship rules apply to all selected rows during bulk operations
* **Undo/redo**: All cascading updates are tracked in the undo stack as a single operation

<Warning title="Same-Level Relationships Only">
  Relationships must be defined between columns at the same binding level (both risk or both task). Cross-level relationships (risk column to task column) are not supported and will be ignored.
</Warning>

See [Enum Columns](/risksheet/reference/columns/enum-columns) for dependent enum configuration details.

## System Field Bindings

Risksheet uses reserved system bindings for internal state management. These bindings are not user-configurable but are documented here for reference.

| System Binding             | Purpose                                                             |
| -------------------------- | ------------------------------------------------------------------- |
| `ID`                       | Standard item identity binding                                      |
| `systemItemId`             | Polarion work item ID for cross-reference and linking               |
| `systemReadOnly`           | Marks entire items as non-editable                                  |
| `systemReadOnlyFields`     | Pipe-delimited string of specific field names that are non-editable |
| `systemItemRevision`       | Work item revision for baseline comparison                          |
| `systemTaskReadOnly`       | Marks linked task items as non-editable                             |
| `systemTaskReadOnlyFields` | Pipe-delimited string of task field names that are non-editable     |
| `reviewsRendered`          | Review status display column                                        |
| `reviewsAdd`               | Review addition control column                                      |

These bindings enable features like permission-based editability, revision tracking, and review workflow visualization. See [System Fields](/risksheet/reference/fields/system-fields) for the complete list.

## Read-Only Field Protection

The binding system enforces read-only protection on specific fields. The following fields are always read-only and cannot be modified through the Risksheet grid:

| Field           | Reason                                                                   |
| --------------- | ------------------------------------------------------------------------ |
| `id`            | Work item identity                                                       |
| `status`        | Controlled by workflow transitions                                       |
| `type`          | Immutable after creation                                                 |
| `project`       | Project assignment is immutable                                          |
| `outlineNumber` | Managed by Polarion document structure                                   |
| `author`        | System-managed creation metadata, set at creation time                   |
| `resolution`    | Controlled by workflow transitions, not set directly from Risksheet      |
| `created`       | System-managed timestamp, set at creation time                           |
| `updated`       | System-managed timestamp, auto-updated by Polarion on every modification |

Save attempts to protected fields are silently ignored.

## Column Properties for Binding Configuration

The full set of column properties that affect field mapping behavior:

| Property       | Type   | Default       | Description                                                              |
| -------------- | ------ | ------------- | ------------------------------------------------------------------------ |
| `bindings`     | string | Same as `id`  | Polarion field name                                                      |
| `type`         | string | Auto-detected | Column data type. Overrides auto-detection.                              |
| `format`       | string | None          | Display format string for dates and numbers                              |
| `cellRenderer` | string | None          | Name of a function defined in `cellDecorators` for custom cell rendering |
| `headerCss`    | string | None          | CSS class applied to the column header                                   |
| `cellCss`      | string | None          | CSS class applied to column cells                                        |

Text wrapping and HTML rendering in cells are controlled through the `styles` section (CSS class definitions) and the `serverRender` column property (for Velocity-driven HTML), not through column-level boolean toggles.

## Complete Example

A sheet configuration demonstrating multiple binding patterns — direct fields, upstream links, and downstream tasks. Severity and occurrence ratings are defined as Polarion enumerations (Administration > Enumerations) and bound to custom fields on the risk work item type.

```yaml theme={null}
dataTypes:
  risk:
    type: risk
    role: has_risk
  task:
    type: mitigationAction
    role: mitigates
    name: Mitigation
    zoomColumn: taskTitle

columns:
  - id: failureMode
    bindings: title
    header: Failure Mode
    type: text
    width: 220
    level: 1
  - id: requirement
    bindings: requirement
    header: Requirement
    type: itemLink
    canCreate: false
    width: 180
    level: 1
  - id: riskCategory
    bindings: riskCategory
    header: Category
    type: enum:riskCategory
    width: 130
    level: 2
  - id: sev
    bindings: sev
    header: Severity (S)
    type: rating:severity
    width: 80
    level: 2
  - id: occ
    bindings: occ
    header: Occurrence (O)
    type: rating:occurrence
    width: 80
    level: 2
  - id: rpn
    bindings: rpn
    header: RPN
    type: int
    formula: commonRpn
    width: 70
    level: 2
  - id: dueDate
    bindings: dueDate
    header: Due Date
    type: date
    width: 120
    level: 2

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

The `severity`, `occurrence`, and `riskCategory` enumerations referenced above are not defined in the sheet configuration — they live as standard Polarion enumerations and are loaded by the server when the grid initializes.

## Related Pages

* [Supported Field Types](/risksheet/reference/fields/supported-field-types) — Polarion field type compatibility and conversion
* [System Fields](/risksheet/reference/fields/system-fields) — system-level binding constants
* [Column Type Reference](/risksheet/reference/columns/column-types) — column definition properties
* [Data Types](/risksheet/reference/columns/data-types) — data type behavior and field mapping
* [Enum Columns](/risksheet/reference/columns/enum-columns) — enum binding and dependent enum configuration
* [Item Link Columns](/risksheet/reference/columns/item-link-columns) — upstream link binding
* [Task Link Columns](/risksheet/reference/columns/task-link-columns) — downstream task binding
* [Configuration Properties Index](/risksheet/reference/configuration/properties-index) — full property reference

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