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

# User Reference Columns

> User reference columns display and manage Polarion user assignments within 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/user-reference-columns/diagram-1.svg?fit=max&auto=format&n=yWl5nA2D0IzEnZC1&q=85&s=df195ec5bad482af3a5d154759683f15" alt="diagram" style={{ maxWidth: "650px", width: "100%" }} width="650" height="150" data-path="risksheet/diagrams/reference/columns/user-reference-columns/diagram-1.svg" />
</Frame>

## Column Properties

| Name          | Type      | Default                                | Description                                                                                                                                 |
| ------------- | --------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | `string`  | Auto-generated from header or bindings | Unique column identifier. If not specified, generated from `header` or `bindings`.                                                          |
| `header`      | `string`  | Required                               | Display text shown in the column header row.                                                                                                |
| `bindings`    | `string`  | Same as `id`                           | Polarion field binding for the user reference. Common values: `assignee` for risk item owner, `task.assignee` for downstream task assignee. |
| `type`        | `string`  | Auto-detected from bindings            | Column type. Set to `ref:user` for user reference columns when auto-detection does not apply.                                               |
| `width`       | `number`  | See application                        | Column width in pixels.                                                                                                                     |
| `readOnly`    | `boolean` | `false`                                | Controls editability. When `true`, displays user ID as a plain string. When `false`, provides a dropdown selector.                          |
| `level`       | `number`  | `1`                                    | Hierarchical level at which this column appears (1 = top level, 2 = second level, etc.). Not set for task columns.                          |
| `headerGroup` | `string`  | None                                   | Header group identifier for multi-level column grouping. Columns with the same `headerGroup` share a group header.                          |
| `filterable`  | `boolean` | See application                        | Controls whether the column supports filtering.                                                                                             |
| `visible`     | `boolean` | `true`                                 | Controls initial visibility of the column. Can be toggled via saved views.                                                                  |

## Column Type and User Role Configuration

User reference columns use the parameterized type `ref:user`. The `userRole` property controls which users appear in the dropdown selector for editable user reference columns, and must be placed **inside a `typeProperties` block** on the column — not as a top-level column property. It specifies a Polarion role to filter the available user list.

| Property                  | Type     | Default         | Description                                                                                                                                                                               |
| ------------------------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `typeProperties.userRole` | `string` | See application | Inside `typeProperties`. Specifies the Polarion role to filter available users. The value `project_assignable` fetches users who have the assignable role in the current project context. |

```yaml theme={null}
{
  "columns": [
    {
      "id": "riskOwner",
      "header": "Risk Owner",
      "bindings": "assignee",
      "type": "ref:user",
      "typeProperties": {
        "userRole": "project_assignable"
      },
      "level": 1,
      "readOnly": false
    }
  ]
}
```

<Warning title="Do not use bare `type: ref`">
  Always use **`type: "ref:user"`** for user reference columns. A bare `type: "ref"` is invalid and **breaks the document load** in current versions, producing a fatal config error (`Index 1 out of bounds for length 1`) that prevents the entire Risksheet from rendering. Likewise, place `userRole` inside `typeProperties` — supplying it as a top-level column property with `type: "ref:user"` raises a runtime error (`Cannot invoke ...getUserRole() because typeProperties is null`).
</Warning>

<Warning title="Cross-Project User Lists">
  When mitigation tasks reside in a different project than the Risksheet document, the `userRole: 'project_assignable'` property fetches users from the **Risksheet's project context**, not from the task's project. This means the dropdown may not include users who are assignable only in the task's project.

  **Workaround:** Use a global Polarion role where the needed persons are added, rather than relying on project-specific roles. Global roles are visible across all projects.
</Warning>

<Info title="Project-dependent user lists">
  Dependent enum support (available in version 25.3.1 and later) may enable project-dependent user lists in the future, allowing the dropdown to respect the task's project context.
</Info>

## Read-Only vs. Editable Behavior

User reference columns behave differently depending on the `readOnly` property:

| Mode      | `readOnly` Value | Display                                     | Editing Behavior                            | Data Handling                                        |
| --------- | ---------------- | ------------------------------------------- | ------------------------------------------- | ---------------------------------------------------- |
| Read-only | `true`           | User ID as plain string text                | No editing allowed; cell is non-interactive | Returns user ID string from work item field          |
| Editable  | `false`          | Dropdown selector populated from `userRole` | User selects from filtered dropdown list    | Clears all existing assignees and adds selected user |

### How Editable User Columns Save Data

When a user selects a value from the dropdown in an editable user reference column, the following sequence occurs:

1. All existing assignees on the work item are cleared
2. The selected user is added as the sole assignee
3. The change is saved to the Polarion work item

<Warning title="Single-User Assignment Only">
  Editable user reference columns currently support **single-user assignment only**. Selecting a new user always replaces all existing assignees. If the work item previously had multiple assignees (set from Polarion's native interface), all but the newly selected user are removed.
</Warning>

### Read-Only Field Protection

The following system-level fields are always read-only regardless of column configuration:

| Field           | Binding            | Reason                                |
| --------------- | ------------------ | ------------------------------------- |
| `id`            | Work item ID       | System-generated, immutable           |
| `status`        | Workflow status    | Changed only via workflow transitions |
| `type`          | Work item type     | Immutable after creation              |
| `project`       | Project identifier | Determined by document location       |
| `outlineNumber` | Outline number     | Managed by document structure         |
| `author`        | Item creator       | Historical record, never changeable   |

Additionally, any column with `readOnly: true` in the configuration silently ignores save attempts.

## PDF Export Behavior

User reference fields in PDF export display user IDs rather than display names. This is an inconsistency with regular enum fields, which export with human-readable titles.

| Field Type                | PDF Export Display   |
| ------------------------- | -------------------- |
| Regular enum              | Display name / title |
| Rating enum               | Numeric ID           |
| User reference / assignee | User ID              |

<Tip title="Consistent Export Formatting">
  Use [Saved Views](/risksheet/reference/saved-views) as an alternative export option when you need user names displayed consistently in PDF export sections. Saved views provide more control over which columns appear and how they are formatted in exports.
</Tip>

## Excel Export Behavior

In Excel exports, user reference columns follow the same pattern as the grid display:

* Read-only user columns export the user ID as a plain string
* The exported file preserves cell background and text colors from the grid (when `includeStyles` is active)
* Column headers are included in bold font at the top of the exported sheet

## Type Conversion Details

Risksheet handles user reference fields through a dynamic type conversion system:

| Direction                | Conversion                                                                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Polarion to Grid (read)  | Reads user ID from work item field. For read-only columns, returns the ID as a string. For editable columns, provides the ID to the dropdown selector. |
| Grid to Polarion (write) | Clears the work item's assignees collection, then adds the selected user. Only executes for non-read-only columns and non-system fields.               |

The type conversion system supports displaying any Polarion field as a user reference column, though the primary use case is the `assignee` field binding.

## Configuration Examples

### Risk Owner Column (Editable)

Assign a risk owner directly from the Risksheet grid:

```yaml theme={null}
{
  "columns": [
    {
      "id": "riskOwner",
      "header": "Risk Owner",
      "bindings": "assignee",
      "type": "ref:user",
      "typeProperties": {
        "userRole": "project_assignable"
      },
      "width": 130,
      "level": 1,
      "headerGroup": "Responsibility",
      "readOnly": false
    }
  ]
}
```

### Mitigation Task Assignee (Editable)

Assign users to downstream mitigation tasks:

```yaml theme={null}
{
  "columns": [
    {
      "id": "taskAssignee",
      "header": "Task Assignee",
      "bindings": "task.assignee",
      "type": "ref:user",
      "typeProperties": {
        "userRole": "project_assignable"
      },
      "width": 130,
      "headerGroup": "Mitigation",
      "readOnly": false
    }
  ]
}
```

### Audit Trail Column (Read-Only)

Display the work item creator for audit purposes:

```yaml theme={null}
{
  "columns": [
    {
      "id": "createdBy",
      "header": "Created By",
      "bindings": "author",
      "type": "ref:user",
      "width": 100,
      "level": 1,
      "readOnly": true
    }
  ]
}
```

### Complete Example

An FMEA configuration with risk owner, task assignee, and audit trail columns:

```yaml theme={null}
{
  "columns": [
    {
      "id": "failureMode",
      "header": "Failure Mode",
      "bindings": "title",
      "width": 200,
      "level": 1
    },
    {
      "id": "riskOwner",
      "header": "Risk Owner",
      "bindings": "assignee",
      "type": "ref:user",
      "typeProperties": {
        "userRole": "project_assignable"
      },
      "width": 130,
      "level": 1,
      "headerGroup": "Responsibility",
      "readOnly": false
    },
    {
      "id": "sev",
      "header": "Severity",
      "bindings": "sev",
      "type": "rating:severity",
      "width": 70,
      "level": 1,
      "headerGroup": "Initial Assessment"
    },
    {
      "id": "occ",
      "header": "Occurrence",
      "bindings": "occ",
      "type": "rating:occurrence",
      "width": 70,
      "level": 1,
      "headerGroup": "Initial Assessment"
    },
    {
      "id": "taskAssignee",
      "header": "Assignee",
      "bindings": "task.assignee",
      "type": "ref:user",
      "typeProperties": {
        "userRole": "project_assignable"
      },
      "width": 130,
      "headerGroup": "Mitigation Tasks",
      "readOnly": false
    },
    {
      "id": "author",
      "header": "Created By",
      "bindings": "author",
      "type": "ref:user",
      "width": 100,
      "level": 1,
      "readOnly": true
    }
  ]
}
```

## Edge Cases and Limitations

| Scenario                                | Behavior                                                                                |
| --------------------------------------- | --------------------------------------------------------------------------------------- |
| Multiple assignees set from Polarion UI | Risksheet displays only the first assignee; editing replaces all with the selected user |
| User not found in project               | User ID is displayed as-is; dropdown may not include the user for re-selection          |
| Cross-project task assignee             | Dropdown shows users from the Risksheet's project, not the task's project               |
| Historical revision view                | User columns become read-only automatically when viewing a non-current revision         |
| Empty assignee field                    | Cell displays empty; no default user is assigned                                        |
| System field binding (e.g., `author`)   | Always read-only regardless of `readOnly` configuration setting                         |

## Related Pages

* [Column Type Reference](/risksheet/reference/columns/column-types) -- overview of all available column types
* [Data Types](/risksheet/reference/columns/data-types) -- complete data type reference including task configuration
* [Saved Views](/risksheet/reference/saved-views) -- column visibility presets for consistent export formatting
* [Enum Columns](/risksheet/reference/columns/enum-columns) -- enum columns with similar dropdown behavior
* [System Fields](/risksheet/reference/fields/system-fields) -- system field bindings and read-only protection
* [Field Mapping](/risksheet/reference/fields/field-mapping) -- how Polarion fields map to Risksheet columns

<LastReviewed date="2026-07-08" />