Skip to main content
diagram

​
multiItem Property

NameTypeDefaultDescription
multiItembooleanfalseIndicates this column displays multiple related items (one-to-many or 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:
ScenarioExample Binding PathDescription
Second linked entity on same parentsystemRequirements.systemRequirement.designRequirements.designRequirementWhen a parent entity links to two different entity types via separate relationships
Verification/validation test casessystemRequirements.systemRequirement.verificationTestCases.verificationTestCaseTest case collections linked to requirements
External referencesdesignRequirements.designRequirement.externalReferences.externalReferenceExternal system links attached to design items
When 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:
NameTypeDefaultDescription
multiItembooleanfalseEnables multi-item display and editing for the column
titlestringNoneDisplay label for the column header
widthnumberNoneColumn width in pixels
headerstringNoneYAML anchor reference to reusable header styling configuration
displaystringidSpecifies which property of the referenced entity to display. Options: title, titleOrName, or a custom property path
columnGroupstringNoneAssigns the column to a visual column group
visiblebooleantrueControls whether the column is shown by default
formatterstringNoneReferences a formatter name from the formatters section
isreadOnlybooleanfalsePrevents 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 domain 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: <WHERE>
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements
            expand:
              - name: externalReferences
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.

​
Domain Model Requirements

The entity types and relationships referenced by multi-item columns must exist in the domain 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.

​
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: <WHERE>
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements
            expand:
              - name: externalReferences
          - name: verificationTestCases
Sources: KB: how-to-add-external-references-column-design-outputs | Tickets: multi-item configuration issues | Code: powersheet.yaml, render-columns.tsx, permissions-levels.template.yaml
KB ArticlesSupport TicketsSource Code
  • powersheet.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/packages/sheet/SheetComponent.tsx
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/packages/sheet/commands/exportXlsx.tsx
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/packages/common/types/api/document.ts
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/packages/sheet/render-columns.tsx