Skip to main content

​
When to Use multiItem

Use multiItem: true when a column binding path points to a many-to-many relationship in the domain model. In these cases, a single parent entity can link to multiple child entities, and those child entities can also link back to multiple parents. Common scenarios include:
  • Verification test cases linked to requirements
  • Validation test cases linked to requirements
  • Risk controls linked to hazards
Without multiItem: true, the column treats the binding as a single-value reference and only displays one item. diagram
The multiItem property works with many-to-many relationships that use association entities in the domain model. It does not support one-to-many relationships. If your relationship is one-to-many (a parent expanding to child rows), use a standard expansion path with nested columns instead.

​
Step 1: Verify the Domain Model Relationship

Before configuring the column, confirm that the relationship in your domain model is defined as many-to-many. The relationship must use an association entity type to connect the two sides. For example, a SystemRequirement linked to multiple VerificationTestCase entities: 
# Domain model excerpt
relationships:
  - name: verificationTestCases
    from: SystemRequirement
    to: VerificationTestCase
    type: many-to-many
The binding path in your column configuration must follow the navigation property names defined in the domain model.

​
Step 2: Add the multiItem Column

In the columns section of your sheet configuration, add a column whose key is the full binding path to the collection navigation property. Set multiItem: true: 
columns:
  verificationTestCases.verificationTestCase:
    title: Verification Test Cases
    multiItem: true
    display: title
    width: 250
PropertyTypeDefaultPurpose
multiItembooleanfalseEnables multi-value display and editing for collection columns
displaystringidWhich property of the referenced entity to show (title, titleOrName, or a custom property path)
When multiItem is true, the cell renders all linked entities as a list and provides a multi-reference picker for adding or removing items.

​
Step 3: Configure the Sources Expansion

The sources section must include an expand entry for the collection relationship. Without this expansion, the column has no data to display: 
sources:
  - id: systemRequirements
    query:
      from: SystemRequirement
    expand:
      - name: verificationTestCases
Each expand entry corresponds to a navigation property in the domain model. The names must match exactly.
If you add multiItem: true to a column but forget the corresponding expand entry in sources, the column appears empty with no error message. Always verify that every multi-item column has a matching expansion path.
For multi-item columns, add a list property to control the reference picker dropdown. The list.search array defines which entity properties users can search when selecting items: 
columns:
  verificationTestCases.verificationTestCase:
    title: Verification Test Cases
    multiItem: true
    display: title
    list:
      search:
        - title
        - id
      createNew: true
  • list.search — array of property names the picker searches against as the user types
  • list.createNew — set to true to allow creating a new entity directly from the picker dropdown without leaving the sheet

​
Step 5: Add Multi-Level Multi-Item Columns

In a full traceability matrix, you may need multi-item columns at multiple levels of the hierarchy. Each level requires its own expansion path in sources: 
sources:
  - id: userNeeds
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: verificationTestCases
          - name: designRequirements
            expand:
              - name: verificationTestCases

columns:
  systemRequirements.systemRequirement:
    title: System Requirements
    multiItem: true
    display: title
    list:
      search:
        - title
        - id

  systemRequirements.systemRequirement.verificationTestCases.verificationTestCase:
    title: Verification Tests (SysReq)
    multiItem: true
    display: title
    list:
      search:
        - title

  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: Design Requirements
    multiItem: true
    display: title

  systemRequirements.systemRequirement.designRequirements.designRequirement.verificationTestCases.verificationTestCase:
    title: Verification Tests (DesReq)
    multiItem: true
    display: title
Notice how each column’s binding path mirrors the nesting in the expand section. Every dot-separated segment must have a corresponding expansion entry.
When a parent entity links to two different entity types (for example, a SystemRequirement linked to both DesignRequirement and VerificationTestCase), the second linked column must use multiItem: true. This is a non-obvious requirement that consistently blocks new users during initial setup.

​
Step 6: Optional Column Settings

You can combine multiItem with other column properties for additional control: 
columns:
  verificationTestCases.verificationTestCase:
    title: Verification Test Cases
    multiItem: true
    display: title
    isReadOnly: true
    columnGroup: testCases
    visible: true
    minWidth: 200
    formatter: statusFormatter
  • isReadOnly — prevents editing while still displaying linked items
  • columnGroup — assigns the column to a visual group (see Configure a Column Group)
  • formatter — applies conditional styling (see Configure a Formatter)
  • visible — set to false to hide the column in the default view while keeping it available in named views (see Create a View)
Begin with a minimal single-item configuration and verify it works before adding multi-item columns. Jumping straight to complex multi-item setups leads to hard-to-diagnose errors. Add one multi-item column at a time and confirm each one displays data correctly before proceeding.

​
Verify Your Configuration

After saving the sheet configuration:
  1. Reload the powersheet document
  2. You should now see the multi-item column displaying linked entities as a comma-separated list in each cell
  3. Click a cell in the multi-item column — a reference picker should appear, allowing you to search, add, or remove linked entities
  4. If the column appears empty, check that the expand path in sources matches the column binding path exactly
The multi-reference picker behavior (including search results and the “Add New” option) depends on the server-side query configuration. If the picker returns unexpected results, verify that the domain model relationship and expansion paths are correctly defined.

​
See Also