User Reference Columns - Nextedy Documentation

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. `ref:user` shows one user; `multiRef:User` shows every assignee of the work item. A column without `type` bound to the `assignee` field is detected as `multiRef:User`. See Single and Multi-Value User Columns.
`multiple`	`boolean`	None	Switches the column between single-value (`false`) and multi-value (`true`) without touching `type`. When set, it wins over `type`; when omitted, `type` (explicit or auto-detected) decides.
`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

A user column is detected automatically from the assignee binding — multi-value by default, or single-value with multiple: false. The userRole property controls which users appear in the drop-down, and must be placed inside a typeProperties block on the column — not as a top-level column property. It names a Polarion role that filters the available user list. The typeProperties block is optional: without it, the column offers the users of project_assignable.

Property	Type	Default	Description
`typeProperties.userRole`	`string`	`project_assignable`	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.

The selector lists the users alphabetically by name.

columns:
  - id: riskOwner
    header: Risk Owner
    bindings: assignee
    typeProperties:
      userRole: project_assignable
    level: 1

Do not use bare type: refWhen you set the type explicitly, always use the full form — type: "ref:user" or type: "multiRef:User". 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 — Risksheet does not read a userRole set as a top-level column property, so the column falls back to project_assignable.

Cross-Project User ListsWhen 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.

Project-dependent user listsDependent 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.

Single and Multi-Value User Columns

A Polarion work item can have any number of assignees. Risksheet offers two column types for them:

Type	Cell shows	Editor	Saving
`ref:user`	One user	Dropdown — pick one user	Replaces all assignees with the selected user
`multiRef:User`	Every assignee, by name	Multi-select list with a search box	Replaces the assignees with exactly the users that are checked

Which type a column gets:

type omitted — a column bound to the assignee field is detected as multiRef:User, so it shows and edits every assignee.
type: "ref:user" — the column stays single-value, exactly as before. Existing configurations that set this type keep their behaviour.
type: "multiRef:User" — the column is multi-value.
multiple — true makes the column multi-value and false single-value, whatever type says.

columns:
  - id: owners
    header: Owners
    bindings: assignee
    width: 150

Restoring Single-Value Behaviour

A column bound to assignee without a type used to be read-only: it listed every assignee as comma-separated names and could not be edited from the grid. The same column is now an editable multi-value picker. No configuration changed, so sheets that relied on an untyped assignee column behave differently after the upgrade. To pin such a column back to a single assignee, add multiple: false:

columns:
  - header: Risk owner
    bindings: assignee
    multiple: false
    width: 150

The cell then shows the first assignee only, and picking a user replaces every assignee with that one.

— automatic — stays on single-value columnsMaking the column single-value does not remove the — automatic — entry from its dropdown — it is offered on every column bound to assignee, single- or multi-value, and no setting turns it off. See Automatic Assignee.

Assignee field onlyA multiRef:User column always reads and writes the work item’s assignees. Bind it to assignee (or task.assignee for downstream tasks); other user fields are not supported as multi-value columns.

Editing a Multi-Value Cell

Start typing in the cell to open the list of users with your text already in the search box, or double-click the cell and open its drop-down.
Type in the Search… box to narrow the list. Searching only filters the list; it never checks or unchecks a user.
Check every user who should be assigned and uncheck the ones who should not.
Leave the cell, then save the sheet.

The saved set replaces the work item’s assignees, the same way Polarion’s own assignee editor does. Unchecking every user removes all assignees. Changes are written to Polarion only when you save the sheet; reloading the page before saving discards them. See Working Sessions. The order of the assignees carries no meaning: saving the same users in a different order does not change the work item, and comparing with a baseline does not mark a reordered cell as changed.

Automatic Assignee

A column bound to the assignee field — ref:user or multiRef:User, on risk items or on downstream tasks — offers an extra option at the top of the list: — automatic —. It lets Polarion choose the assignee from the item’s type and categories.

When the sheet is saved, Risksheet first writes every other field of the item and then asks Polarion to assign it, so the categories you just changed are taken into account.
After the save, the cell shows the users Polarion assigned.
A new task added from the sheet starts with — automatic — in its assignee column. Pick a user instead to assign the task explicitly.

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	`ref:user`: clears all existing assignees and adds selected user. `multiRef:User`: replaces the assignees with the checked users

How Editable User Columns Save Data

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

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

ref:user Columns Keep One AssigneeA ref:user column supports 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. Use a multiRef:User column to keep and edit every assignee — see Single and Multi-Value User Columns.

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 (`ref:user`)	User ID
Multi-value assignee (`multiRef:User`)	User names

Consistent Export FormattingUse 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.

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
multiRef:User columns export the names of all assignees
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 (`ref:user`) or every checked user (`multiRef: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:

columns:
  - id: riskOwner
    header: Risk Owner
    bindings: assignee
    multiple: false
    width: 130
    level: 1
    headerGroup: Responsibility

Mitigation Task Assignee (Single-Value)

Assign one user to each downstream mitigation task:

columns:
  - id: taskAssignee
    header: Task Assignee
    bindings: task.assignee
    multiple: false
    width: 130
    headerGroup: Mitigation

Mitigation Task Assignees (Multi-Value)

Assign several users to each downstream mitigation task — multi-value is the default for an assignee binding, so no type is needed:

columns:
  - id: taskAssignees
    header: Task Assignees
    bindings: task.assignee
    width: 180

Audit Trail Column (Read-Only)

Display the work item creator for audit purposes:

columns:
  - id: createdBy
    header: Created By
    bindings: author
    readOnly: true
    width: 100
    level: 1

Complete Example

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

columns:
  - id: failureMode
    header: Failure Mode
    bindings: title
    width: 200
    level: 1
  - id: riskOwner
    header: Risk Owner
    bindings: assignee
    multiple: false
    width: 130
    level: 1
    headerGroup: Responsibility
  - 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: taskAssignees
    header: Assignees
    bindings: task.assignee
    width: 130
    headerGroup: Mitigation Tasks
  - id: author
    header: Created By
    bindings: author
    readOnly: true
    width: 100
    level: 1

Edge Cases and Limitations

Scenario	Behavior
Multiple assignees set from Polarion UI	A `multiRef:User` column shows all of them. A `ref:user` column 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. A new task added from the sheet starts with — automatic — instead
System field binding (e.g., `author`)	Always read-only regardless of `readOnly` configuration setting

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

​Column Properties

​Column Type and User Role Configuration

​Single and Multi-Value User Columns

​Restoring Single-Value Behaviour

​Editing a Multi-Value Cell

​Automatic Assignee

​Read-Only vs. Editable Behavior

​How Editable User Columns Save Data

​Read-Only Field Protection

​PDF Export Behavior

​Excel Export Behavior

​Type Conversion Details

​Configuration Examples

​Risk Owner Column (Editable)

​Mitigation Task Assignee (Single-Value)

​Mitigation Task Assignees (Multi-Value)

​Audit Trail Column (Read-Only)

​Complete Example

​Edge Cases and Limitations

​Related Pages

Column Properties

Column Type and User Role Configuration

Single and Multi-Value User Columns

Restoring Single-Value Behaviour

Editing a Multi-Value Cell

Automatic Assignee

Read-Only vs. Editable Behavior

How Editable User Columns Save Data

Read-Only Field Protection

PDF Export Behavior

Excel Export Behavior

Type Conversion Details

Configuration Examples

Risk Owner Column (Editable)

Mitigation Task Assignee (Single-Value)

Mitigation Task Assignees (Multi-Value)

Audit Trail Column (Read-Only)

Complete Example

Edge Cases and Limitations

Related Pages