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

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

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

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.

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.

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:

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

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.

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

Use 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
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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

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

​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 (Editable)

​Audit Trail Column (Read-Only)

​Complete Example

​Edge Cases and Limitations

​Related Pages

Column Properties

Column Type and User Role Configuration

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 (Editable)

Audit Trail Column (Read-Only)

Complete Example

Edge Cases and Limitations

Related Pages