Multi-Item Columns - Nextedy Documentation

`multiItem` Property

Name	Type	Default	Description
`multiItem`	`boolean`	`false`	Indicates this column displays multiple related items (many-to-many relationship). Enables multi-value display and editing.

When multiItem is set to true, the column cell renders all linked entities for the current row, rather than a single value. Users can add, remove, and browse multiple related items through a dedicated picker interface.

When to Use Multi-Item Columns

Multi-item columns are required in these scenarios:

Scenario	Example Binding Path	Description
Second linked entity on same parent	`systemRequirements.systemRequirement.designRequirements.designRequirement`	When a parent entity links to two different entity types via separate relationships
Verification/validation test cases	`systemRequirements.systemRequirement.verificationTestCases.verificationTestCase`	Test case collections linked to requirements
External references	`designRequirements.designRequirement.externalReferences.externalReference`	External system links attached to design items

Required for Second Linked Entity TypesWhen a sheet has two work item types linked to the same parent entity (e.g., design outputs and design verifications both linked to system requirements), the second linked column must be declared with multiItem: true. This is a non-obvious requirement that commonly blocks new users during initial setup.

Column Configuration Properties

The following properties apply when configuring a multi-item column:

Name	Type	Default	Description
`multiItem`	`boolean`	`false`	Enables multi-item display and editing for the column
`title`	`string`	None	Display label for the column header
`width`	`number`	None	Column width in pixels
`header`	`string`	None	YAML anchor reference to reusable header styling configuration
`display`	`string`	`id`	Specifies which property of the referenced entity to display. Options: `title`, `titleOrName`, or a custom property path
`columnGroup`	`string`	None	Assigns the column to a visual column group
`visible`	`boolean`	`true`	Controls whether the column is shown by default
`formatter`	`string`	None	References a formatter name from the formatters section
`isReadOnly`	`boolean`	`false`	Prevents user editing of this column (deprecated in favor of `formatter=readOnly`)

Binding Path Syntax

Multi-item columns use dot-separated binding paths that follow the relationship chain defined in the data model. The path alternates between the collection navigation property and the entity type:

<collection>.<entityType>.<collection>.<entityType>...

For a full reference on binding path construction, see Binding Syntax.

Configuration Example

The following example adds an external references multi-item column to a design requirement:

columns:
  # Parent entity columns
  title:
    title: User Need
    width: 300
    hasFocus: true

  # Multi-item column for external references linked to design requirements
  systemRequirements.systemRequirement.designRequirements.designRequirement.externalReferences.externalReference:
    title: External References
    width: 200
    multiItem: true
    header: *blue
    display: titleOrName

Sources Configuration

Multi-item columns require their expansion paths to be declared in the sources section. The expand array must include the full chain of relationships:

sources:
  - name: requirement
    model: rtm
    query:
      from: UserNeed
      where: "type = 'UserNeed'"
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements
            expand:
              - name: externalReferences

Match Sources to Columns

Every multi-item column binding path must have a corresponding expansion path in the sources configuration. If the expansion is missing, the column will not load related entities.

For source configuration details, see Sources.

Data Model Requirements

The entity types and relationships referenced by multi-item columns must exist in the data model:

domainModelTypes:
  ExternalReference:
    # entity type configuration

relationships:
  - from: ExternalReference
    to: DesignRequirement
    linkRole: relatesTo

Ensure the Polarion link role is configured to allow links between the relevant work item types. See Link Roles and Relationships.

Copy and Paste Behavior

Starting with Powersheet 26.9.0, copy and paste link and unlink work items in a multi-item column bound to a many-to-many relationship. Copying a multi-item cell (Ctrl+C) puts its linked work item IDs on the clipboard as a comma-separated list, for example REQ-101,REQ-102. Pasting such a list (Ctrl+V) into a multi-item cell, or into a range of cells in that column, replaces the cell’s links:

The ID is…	What happens
In the paste, not yet linked	The work item is linked
Linked, but not in the paste	The work item is unlinked
Linked and in the paste	The link is left as it is

Spaces around the IDs are ignored, an ID listed twice is linked once, and pasting an empty value removes every link from the cell.

Picker scope — a paste can only link work items the column’s picker would offer for that row: the same data-model constraints, picker filters and document scope apply. IDs the sheet has not loaded are looked up on the server first, while Resolving pasted items… is shown.
Prerequisites — you need permission to create links in the column, and to remove them if the paste removes some (see Configure Permissions). The row must already have a work item at the column’s level. Read-only cells in the selected range are skipped without a message.
No partial stripping — if none of the new IDs pasted into a cell can be linked, the cell keeps its current links. If some can be linked, Powersheet links those and removes the links the paste left out.
Feedback — a confirmation such as Linked 2 items., Unlinked 1 item. or Linked 2, unlinked 1 in 3 rows. appears only when the paste was applied in full. Otherwise a warning or an error names the reason.
Undo and save — one Ctrl+Z undoes the whole paste in every row it touched, and Ctrl+Y redoes it. Pasted links are pending changes, like links picked in the picker, and are written to Polarion only when you click Save.

Messages After a Paste

Message	Meaning	What to do
Could not resolve: <IDs>. They either do not exist or are not allowed in this column.	These IDs were skipped. Either no such work item exists, or the column’s picker would not offer it for that row. If the lookup itself failed, the cell was left unchanged.	Check the IDs for typos, and check that the work items appear in the picker for that cell.
Linking is not permitted in: <columns>	You are not allowed to add links in these columns, or to remove links when your paste removes some. The cells were not changed.	Ask your administrator for the permission, or paste into a column you may edit.
Cannot link in: <columns>. Check the column’s binding.	The column is not bound to a relationship that can hold links. The cells were not changed.	Check the column’s binding in the sheet configuration.
Add the item before linking to it.	A target row has no work item at the column’s level, so there is nothing to link from.	Create the work item in that row first, then paste again.
The sheet changed while the pasted items were loading. Some rows were skipped — paste again.	While Powersheet was looking up the pasted IDs, a target row was removed or filtered out, its work item was deleted, or the column was hidden. Those rows were skipped.	Paste again.
Pasting across multiple levels not supported. Valid columns: <columns>	The selected range spans columns of different levels. Only the columns at the level of the leftmost column were pasted.	Paste into columns of one level at a time.
Pasting links failed.	The paste could not be completed.	Check the cell, then paste again.

Export Behavior

When exporting to Excel, multi-item cells render each item on a separate line within the same cell. Comma-separated values in the sheet are converted to newline-separated lists in the exported XLSX file.

Complete YAML Example

header: &blue
  style:
    background: blue
    color: white

columnGroups:
  DesignReq:
    groupName: Design Requirements
    groupStyle: blue
    headerStyle: blueHeader

columns:
  title:
    title: User Need
    width: 300
    hasFocus: true
    sort: asc

  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 250

  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Requirement
    width: 250
    columnGroup: DesignReq

  systemRequirements.systemRequirement.designRequirements.designRequirement.externalReferences.externalReference:
    title: External References
    width: 200
    multiItem: true
    header: *blue
    display: titleOrName
    columnGroup: DesignReq

  systemRequirements.systemRequirement.verificationTestCases.verificationTestCase:
    title: Verification Tests
    width: 200
    multiItem: true
    header: *blue

sources:
  - name: requirement
    model: rtm
    query:
      from: UserNeed
      where: "type = 'UserNeed'"
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements
            expand:
              - name: externalReferences
          - name: verificationTestCases

Columns — base column configuration reference
Binding Syntax — dot-separated path construction rules
Sources — data source and expansion path configuration
Relationships — data model relationship definitions
Columns — full list of column-level properties

​multiItem Property

​When to Use Multi-Item Columns

​Column Configuration Properties

​Binding Path Syntax

​Configuration Example

​Sources Configuration

​Data Model Requirements

​Copy and Paste Behavior

​Messages After a Paste

​Export Behavior

​Complete YAML Example

​Related Pages

`multiItem` Property

When to Use Multi-Item Columns

Column Configuration Properties

Binding Path Syntax

Configuration Example

Sources Configuration

Data Model Requirements

Copy and Paste Behavior

Messages After a Paste

Export Behavior

Complete YAML Example

Related Pages