Skip to main content

​
Identify the Error

Multi-item column errors manifest as:
  • A relationship column shows only one related item instead of multiple
  • The cell editor opens as a single-value picker instead of a multi-item picker
  • Saving linked work items fails or creates incorrect associations
  • The second linked entity type column displays blank cells

​
Step 1: Set multiItem: true on the Column

The most common cause is a missing multiItem property in the sheet configuration. When a column represents a collection (one-to-many or many-to-many relationship), you must explicitly set multiItem: true: 
columns:
  systemRequirements.systemRequirement.title:
    title: "Sys Req Title"
    width: 200
    hasFocus: true

  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: "Design Req Title"
    width: 200
    multiItem: true    # Required for collection columns
When a parent entity links to multiple child entity types (e.g., SystemRequirement links to both DesignRequirement and VerificationTestCase), the second and subsequent linked columns must be declared with multiItem: true in the sheet configuration. This is a non-obvious requirement that frequently blocks new users.

​
Step 2: Verify the Relationship Cardinality

The multiItem property should align with the relationship cardinality in your domain model:
CardinalitymultiItem Needed?Display Behavior
one-to-oneNoSingle-value cell
many-to-oneNoSingle-value cell
one-to-manyYesMultiple items with separators
many-to-manyYesMultiple items with linking mode
Check your domain model relationships section: 
relationships:
  - from: SystemRequirement
    to: DesignRequirement
    cardinality: one-to-many       # Requires multiItem: true
    storage: linkedWorkItems
    linkRole: has_parent
    direct:
      name: designRequirements
    back:
      name: systemRequirement

​
Step 3: Check the Expansion Path

Multi-item columns require the corresponding expansion path to be defined in the sources section. Without expansion, the related entities will not load: 
sources:
  - model: my-model
    from: UserNeed
    expand:
      - systemRequirements.systemRequirement:
          - designRequirements.designRequirement        # Must be expanded
          - verificationTestCases.verificationTestCase   # Must be expanded
diagram

​
Step 4: Configure the Display Property

Multi-item cells display a list of related items. Control what text appears for each item using the display property: 
columns:
  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: "Design Requirements"
    width: 250
    multiItem: true
    display: title           # Show title of each related item
Available display values include id, title, and titleOrName.
Begin with a single-entity configuration that works correctly, then add multi-item columns one at a time. Jumping directly to complex multi-item configurations makes errors difficult to diagnose.

​
Step 5: Multi-Item Editing Behavior

When multiItem: true is set correctly, double-clicking a multi-item cell opens an autocomplete editor with a dropdown for selecting additional items. Each item displays with a separator and an external link icon for navigation. Multi-item columns also support:
  • Filtering: Click the filter icon to filter by item combinations
  • Linking mode: For many-to-many relationships, use linking mode to create associations

​
Verification

After applying the fix:
  1. Save the sheet configuration
  2. Reload the powersheet document
  3. You should now see multiple related items displayed in the column, separated by semicolons
  4. Double-click the cell to verify the multi-item picker opens with autocomplete functionality

​
See Also

Sources: powersheet.yaml, multi-item-picker.spec.ts, permissions-levels.template.yaml, ticket insights
Support TicketsSource Code
  • powersheet.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/packages/sheet/commands/exportXlsx.tsx
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/permissions-levels.template.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/cypress/e2e/Sheet/multi-item-picker.spec.ts
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/packages/sheet/commands/filter-items-for-review.ts