Configure Sources - Nextedy Documentation

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, the data model it queries against, a query targeting an entity type, and optional expansion paths:

sources:
  - id: user_needs
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements

Property	Required	Description
`id`	Yes	Unique identifier for the source, referenced from tool settings
`model`	Yes	Data model name the source queries (must match a configured model, e.g. `rtm`)
`query.from`	Yes	Root entity type to query (must exist in the data model)
`query.where`	No	Filter predicate to restrict which entities are loaded
`query.orderBy`	No	Server-side sort order for the query results
`query.take`	No	Maximum number of root entities to load
`expand`	No	Array of expansion paths for loading related entities
`entityFactory`	No	Default property values applied when creating new entities

The Model Helper widget visualizes the data 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 data model relationships:

sources:
  - id: user_needs
    model: rtm
    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 data model relationships.

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:

Cardinality	Model Direction	Source Expand	Column Binding	UI Behavior
N:1 (many-to-one)	`direct` name (singular)	`- name: chapter`	`chapter`, `chapter.title`	Single-value reference picker
1:N (one-to-many)	`back` name (plural)	`- name: userNeeds`	`userNeeds`	Child rows (new sheet level)
M:N (many-to-many)	`back` name (plural)	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-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
    model: rtm
    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
    model: rtm
    query:
      from: UserNeed
      where:
        dueDate:
          ">": "() => new Date().toISOString()"

sources:
  - id: filtered_by_param
    model: rtm
    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
    model: rtm
    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 and reference a model:

sources:
  - id: user_needs
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

  - id: hazards
    model: rtm
    query:
      from: Hazard
    expand:
      - name: riskControls
        expand:
          - name: riskControl

Multiple sources allow a single sheet to display data from different parts of the data 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
    model: rtm
    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
    model: rtm
    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:

Open the Powersheet document in Polarion
The sheet should load and display the root entities defined by query.from
Verify that expansion arrows appear on rows — clicking them loads related entities at each level
Create a new entity to confirm entityFactory defaults are applied correctly
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 data model relationships.

​Define a Basic Source

​Expand Relationships

​Expansion by Cardinality

​Filter with a WHERE Clause

​Set Default Values with Entity Factory

​Configure Multiple Sources

​Limit Results with Take

​Complete Configuration Example

​Verify Your Configuration

​See Also

Define a Basic Source

Expand Relationships

Expansion by Cardinality

Filter with a WHERE Clause

Set Default Values with Entity Factory

Configure Multiple Sources

Limit Results with Take

Complete Configuration Example

Verify Your Configuration

See Also