Sources - Nextedy Documentation

Sources are the bridge between the data model (which defines entity types and relationships) and the sheet columns (which define how data is displayed). The data model declares what entities and relationships exist; sources declare which of those entities to load and which relationships to expand; columns declare how to render the resulting data.

Understanding how sources connect to the data model and columns is essential. See Cardinality for the full relationship between these three configuration layers.

Source Data Flow

Top-Level Source Properties

The sources key is a top-level array in the sheet configuration YAML, alongside columns, views, formatters, and other sections.

Property	Type	Required	Default	Description
`id`	string	Yes	None	Unique identifier for this data source. Referenced by tool settings to bind a source to a sheet.
`title`	string	No	None	Human-readable label displayed in the Powersheet UI for this data source.
`model`	string	Yes	None	Reference to the data model that defines entity types and relationships.
`query`	object	Yes	None	Query definition specifying which root entities to load. See Query Properties.
`expand`	array	No	`[]`	Expansion paths for loading related entities through data model relationships. See Expand Properties.
`entityFactory`	object	No	None	Default property values applied when creating new entities from this source. See Entity Factory.

Source Ordering

The first source in the array (sources[0]) is the primary data source for the sheet. Additional sources can define secondary entity types for multi-type configurations.

Query Properties

The query object within each source defines how to retrieve root-level entities from Polarion.

Property	Type	Required	Default	Description
`query.from`	string	Yes	None	Root entity type to query. Must match an entity type defined in the data model’s `domainModelTypes`.
`query.where`	object	No	None	Filter predicate restricting which entities are loaded. Supports dynamic value expressions with `() =>` syntax.
`query.take`	number	No	None	Maximum number of root entities to return. Limits the result set size.
`query.orderBy`	array	No	None	Array of sort specifications applied server-side to order results before they reach the sheet. Each entry specifies a property name and direction.

Dynamic Where Clauses

The where property supports dynamic value expressions using the () => syntax. The predicate value is evaluated at runtime, allowing queries that depend on document parameters, the current date, or other context values. The resulting value must match the expected type for the property being filtered. For example, date comparisons require ISO 8601 format strings. Static filter example:

sources:
  - id: user_needs
    query:
      from: UserNeed
      where:
        severity:
          "!=": null

Dynamic filtering with document parameters:

sources:
  - id: filtered_items
    query:
      from: UserNeed
      where:
        Client:
          "==": "() => `${context.parameters.client} ${context.parameters.status}`"

Date-based filtering example:

sources:
  - id: future_items
    query:
      from: UserNeed
      where:
        dueDate:
          ">": "() => new Date().toISOString()"

Dynamic expressions must be valid JavaScript arrow functions starting with () =>. The resulting value must be in the correct format for the property type. For dates, always use .toISOString() in the expression to produce a properly formatted string.

Expand Properties

The expand array defines which related entities to load by traversing navigation properties declared in the data model relationships. Expansion paths determine the hierarchical depth of the sheet and directly control which columns can be bound to the loaded data.

Property	Type	Required	Default	Description
`expand[].name`	string	Yes	None	Navigation property name to expand. Must match a `direct` or `back` name from the data model relationships.
`expand[].expand`	array	No	None	Nested expansion for loading multi-level relationships. Same structure as the parent `expand`.
`expand[].entityFactory`	object	No	None	Default values for new entities created at this expansion level. See Entity Factory.

Single-Level Expansion

For one-to-many (1:N) or many-to-one (N:1) relationships, a single expansion level is sufficient. N:1 example (each UserNeed belongs to one Chapter):

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter

Here chapter is a direct navigation property from the data model, loading the single parent Chapter entity for each UserNeed. 1:N example (each Chapter has many child UserNeed entities):

sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds

Here userNeeds is a back navigation property. The expansion creates child rows in the sheet for each related UserNeed.

Nested Expansion (Multi-Level)

For many-to-many (M:N) relationships, or when building deep hierarchies, use nested expand entries. M:N relationships use an association entity, so the expansion path traverses two levels: the association collection and then the target entity.

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement

This creates a four-level hierarchy: UserNeed > SystemRequirement (via M:N association) > DesignRequirement (via M:N association). Each M:N hop requires two expand levels: one for the association collection (systemRequirements) and one for the target entity (systemRequirement).

There is no hard limit on nesting depth, but deeper hierarchies increase data load and rendering time. A typical RTM configuration uses 3-5 expansion levels.

Cardinality and Expand Patterns

The relationship cardinality in the data model determines the correct expand pattern:

Cardinality	Model Direction	Source Expand	Column Binding	UI Behavior
N:1	`direct` name (e.g., `chapter`)	`- name: chapter`	`chapter`, `chapter.title`	Single-value reference picker
1:N	`back` name (e.g., `userNeeds`)	`- name: userNeeds`	`userNeeds`	Child rows (new sheet level)
M:N	`back` name (e.g., `systemRequirements`)	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

For comprehensive examples of each cardinality pattern with matching data model, source, and column configurations, see Cardinality.

Entity Factory

The entityFactory object defines default property values that are automatically applied when a user creates a new entity from the sheet. This can be specified at the source level (for root entities) or within an expand entry (for child entities at that expansion level).

Property	Type	Required	Default	Description
`entityFactory`	object	No	None	Key-value pairs where each key is a property name and each value is the default. Values can be strings, numbers, booleans, or null.

sources:
  - id: user_needs
    query:
      from: UserNeed
    entityFactory:
      severity: "medium"
      status: "draft"
    expand:
      - name: systemRequirements
        entityFactory:
          status: "proposed"
        expand:
          - name: systemRequirement

In this example, new UserNeed entities default to severity: "medium" and status: "draft", while new association entities at the systemRequirements level default to status: "proposed".

Dynamic Entity Factory Values

Entity factory values support dynamic value expressions using the () => syntax, allowing defaults that reference document parameters or computed values:

entityFactory:
  Client: "() => context.parameters.client"
  CreatedDate: "() => new Date().toISOString()"

Complete YAML Example

A full RTM (Requirements Traceability Matrix) source configuration demonstrating multi-level expansion, query filtering, and entity factories:

sources:
  - id: user_needs
    title: User Needs
    model: rtm
    query:
      from: UserNeed
      where:
        severity:
          "!=": null
    entityFactory:
      severity: "medium"
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement

This configuration:

Queries all UserNeed entities where severity is not null
Expands through the M:N relationship to SystemRequirement via the systemRequirements association
Further expands through the M:N relationship to DesignRequirement via the designRequirements association
Sets a default severity of "medium" for newly created UserNeed entities

Alternative: Hazard-Based Source

A risk management source starting from Hazard entities:

sources:
  - id: hazards
    title: Hazards
    query:
      from: Hazard
    expand:
      - name: riskControls
        expand:
          - name: riskControl

Configuration Scoping

Sheet configurations (including sources) can be defined at two scopes:

Scope	Location	Behavior
Project	Project SVN repository	Available only to the specific project. Listed without suffix in the configuration picker.
Global	Global configuration directory	Available to all projects. Listed with a `(Global)` suffix in the configuration picker.

Both global and project-specific configurations are discovered automatically and presented in the Administration > Nextedy Powersheet configuration interface. No default configuration is predefined; administrators must explicitly select a configuration for each document.

Interaction with Other Configuration Sections

Sources do not exist in isolation. They connect to several other sheet configuration sections:

Columns: Column binding paths (the key of each column entry) must align with the navigation properties defined in the source expansion paths. A column key like systemRequirements.systemRequirement.title requires that the source expands through systemRequirements and then systemRequirement.
Views: Views override column visibility but do not change source definitions. The same sources feed all views.
Formatters: Formatters apply conditional styling to cells. The context.item available in formatter expressions refers to entities loaded by the sources.
Sort By: Client-side sorting is applied after source data is loaded. The columnId in sortBy entries must reference columns that are bound to source data.
Binding Syntax: The dot-notation paths used in column keys directly mirror the navigation property names from source expansion paths.
Constraints: A source’s query/where filters which root entities load at the sheet level. Restricting which items can be picked, linked, or created (or scoping a load to the current document) is defined separately as data-model constraints (load/pick/create), not in sources. The two are independent layers that combine with AND; they are not alternative formats.

Best Practices

Begin with a minimal single-source configuration and extend incrementally. Jumping directly to complex multi-source, multi-level configurations leads to hard-to-diagnose errors. Validate each expansion level before adding the next.

Match expand to columns: Every column binding path that traverses a navigation property requires a corresponding expand entry in the source. A missing expand results in empty columns.
Use entity factories for required fields: If the target Polarion work item type has required custom fields, set defaults in entityFactory to avoid save validation errors.
Limit query scope with where: Use filter predicates to reduce the number of root entities loaded, improving sheet load performance.
Name sources descriptively: Use meaningful id values (e.g., user_needs, hazards) rather than generic names. The title property provides the human-readable label in the UI.

​Source Data Flow

​Top-Level Source Properties

​Query Properties

​Dynamic Where Clauses

​Expand Properties

​Single-Level Expansion

​Nested Expansion (Multi-Level)

​Cardinality and Expand Patterns

​Entity Factory

​Dynamic Entity Factory Values

​Complete YAML Example

​Alternative: Hazard-Based Source

​Configuration Scoping

​Interaction with Other Configuration Sections

​Best Practices

Source Data Flow

Top-Level Source Properties

Query Properties

Dynamic Where Clauses

Expand Properties

Single-Level Expansion

Nested Expansion (Multi-Level)

Cardinality and Expand Patterns

Entity Factory

Dynamic Entity Factory Values

Complete YAML Example

Alternative: Hazard-Based Source

Configuration Scoping

Interaction with Other Configuration Sections

Best Practices