Skip to main content

​
Define a Basic Source

The sources section is an array at the root level of your sheet configuration YAML. Each source specifies a unique identifier, a query targeting an entity type, and optional expansion paths: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
PropertyRequiredDescription
idYesUnique identifier for the source, referenced from tool settings
query.fromYesRoot entity type to query (must exist in the domain model)
query.whereNoFilter predicate to restrict which entities are loaded
query.orderByNoServer-side sort order for the query results
query.takeNoMaximum number of root entities to load
expandNoArray of expansion paths for loading related entities
entityFactoryNoDefault property values applied when creating new entities
The Model Helper widget visualizes the domain model structure and correct expansion paths. See Use Model Helper Widget for details.

​
Expand Relationships

The expand array defines which related entities are loaded alongside the root entity. Each entry uses the name property corresponding to a navigation property from your domain model relationships: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement
Nested expand entries create multi-level hierarchies. The expansion path structure must match the direct and back navigation property names defined in your domain model relationships. diagram
Begin with a single-level expansion and verify it loads correctly before adding deeper levels. Jumping straight to complex multi-level expansions leads to hard-to-diagnose errors that are difficult to trace.

​
Expansion by Cardinality

The cardinality of a relationship determines the expand pattern and how columns bind to expanded data:
CardinalityModel DirectionSource ExpandColumn BindingUI Behavior
N:1 (many-to-one)direct name (singular)- name: chapterchapter, chapter.titleSingle-value reference picker
1:N (one-to-many)back name (plural)- name: userNeedsuserNeedsChild rows (new sheet level)
M:N (many-to-many)back name (plural)- name: systemRequirements then - name: systemRequirementsystemRequirements.systemRequirementMulti-item reference picker
For many-to-many relationships, the expand must go through the association entity first, then to the target entity. This two-level expand pattern is required: 
expand:
  - name: systemRequirements       # association collection
    expand:
      - name: systemRequirement    # target entity
For a complete walkthrough of expansion patterns, see Expand Navigation Properties.

​
Filter with a WHERE Clause

Use the query.where property to restrict which entities are loaded. The where clause uses predicate syntax: 
sources:
  - id: active_needs
    query:
      from: UserNeed
      where:
        severity:
          "!=": "low"
    expand:
      - name: systemRequirements
You can also use dynamic value expressions with the () => arrow function syntax to build runtime-evaluated filters. For example, to filter by a date or a document parameter: 
sources:
  - id: recent_items
    query:
      from: UserNeed
      where:
        dueDate:
          ">": "() => new Date().toISOString()"

sources:
  - id: filtered_by_param
    query:
      from: UserNeed
      where:
        Client:
          "==": "() => `${context.parameters.client}`"
The () => notation evaluates at runtime. For date predicates, ensure the expression returns an ISO string using .toISOString(). For parameters, use context.parameters.<name> to inject values from the document configuration.

​
Set Default Values with Entity Factory

The entityFactory property defines default property values applied when a user creates a new entity from the sheet. This works at any expand level: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    entityFactory:
      Status: "Planned"
      Priority: "Medium"
    expand:
      - name: systemRequirements
        entityFactory:
          Status: "Draft"
        expand:
          - name: systemRequirement
Entity factory values can also use dynamic expressions: 
entityFactory:
  Client: "() => context.parameters.client"

​
Configure Multiple Sources

A sheet configuration can define multiple sources. Each source must have a unique id: 
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

  - id: hazards
    query:
      from: Hazard
    expand:
      - name: riskControls
        expand:
          - name: riskControl
Multiple sources allow a single sheet to display data from different parts of the domain model, each with its own query filters and expansion hierarchy.

​
Limit Results with Take

Use query.take to cap the number of root entities returned by a source. This is useful for large datasets where loading all entities would impact performance: 
sources:
  - id: top_items
    query:
      from: UserNeed
      take: 100
      orderBy: severity desc
    expand:
      - name: systemRequirements
When using take to limit results, pair it with orderBy so you control which entities are included. Without ordering, the subset returned is unpredictable.

​
Complete Configuration Example

Here is a full sources section for a requirements traceability matrix that queries user needs, expands through system requirements to design requirements, and sets default values for new entities: 
sources:
  - id: user_needs
    query:
      from: UserNeed
      where:
        severity:
          "!=": "low"
      orderBy: title asc
    entityFactory:
      Status: "Planned"
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            entityFactory:
              Status: "Draft"
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement

​
Verify Your Configuration

After saving your sheet configuration YAML:
  1. Open the Powersheet document in Polarion
  2. The sheet should load and display the root entities defined by query.from
  3. Verify that expansion arrows appear on rows — clicking them loads related entities at each level
  4. Create a new entity to confirm entityFactory defaults are applied correctly
  5. If using where filters, confirm that only matching entities appear
You should now see the sheet populated with your source data and the expansion hierarchy matching your domain model relationships.

​
See Also