> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sources

> The `sources` section of a Nextedy POWERSHEET sheet configuration defines an array of data source objects that specify which entities to load from Polarion and how to traverse relationships via expansion paths.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

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.

<Tip title="Configuration Layers">
  Understanding how sources connect to the data model and columns is essential. See [Cardinality](/powersheet/reference/data-model/cardinality) for the full relationship between these three configuration layers.
</Tip>

## Source Data Flow

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/sheet-config/sources/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=1f75d8edbe1c037c0ff21847ba5ade43" alt="diagram" style={{ width: "620px", maxWidth: "100%" }} width="620" height="200" data-path="powersheet/diagrams/reference/sheet-config/sources/diagram-1.svg" />
</Frame>

## 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](#query-properties).                                                                           |
| `expand`        | array  | No       | `[]`    | Expansion paths for loading related entities through data model [relationships](/powersheet/reference/data-model/relationships). See [Expand Properties](#expand-properties). |
| `entityFactory` | object | No       | None    | Default property values applied when creating new entities from this source. See [Entity Factory](#entity-factory).                                                           |

<Accordion title="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.
</Accordion>

## 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](/powersheet/reference/sheet-config/dynamic-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](/powersheet/reference/sheet-config/dynamic-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:**

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
      where:
        severity:
          "!=": null
```

**Dynamic filtering with document parameters:**

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

**Date-based filtering example:**

```yaml theme={null}
sources:
  - id: future_items
    query:
      from: UserNeed
      where:
        dueDate:
          ">": "() => new Date().toISOString()"
```

<Warning title="Dynamic Expression Format">
  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.
</Warning>

## Expand Properties

The `expand` array defines which related entities to load by traversing navigation properties declared in the data model [relationships](/powersheet/reference/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](#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`):

```yaml theme={null}
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):

```yaml theme={null}
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.

```yaml theme={null}
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`).

<Tip title="Expansion Depth">
  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.
</Tip>

### 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](/powersheet/reference/data-model/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. |

```yaml theme={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](/powersheet/reference/sheet-config/dynamic-expressions) using the `() =>` syntax, allowing defaults that reference document parameters or computed values:

```yaml theme={null}
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:

```yaml theme={null}
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:

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

### Alternative: Hazard-Based Source

A risk management source starting from `Hazard` entities:

```yaml theme={null}
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](/powersheet/reference/sheet-config/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](/powersheet/reference/sheet-config/views):** Views override column visibility but do not change source definitions. The same sources feed all views.
* **[Formatters](/powersheet/reference/sheet-config/formatters):** Formatters apply conditional styling to cells. The `context.item` available in formatter expressions refers to entities loaded by the sources.
* **[Sort By](/powersheet/reference/sheet-config/sortby):** 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](/powersheet/reference/sheet-config/binding-syntax):** The dot-notation paths used in column keys directly mirror the navigation property names from source expansion paths.
* **[Constraints](/powersheet/reference/data-model/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

<Tip title="Start Simple">
  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.
</Tip>

* **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.

***

**Related pages:**
[Sheet Configuration Reference](/powersheet/reference/sheet-config/index) |
[Columns](/powersheet/reference/sheet-config/columns) |
[Relationships](/powersheet/reference/data-model/relationships) |
[Cardinality](/powersheet/reference/data-model/cardinality) |
[Dynamic Value Expressions](/powersheet/reference/sheet-config/dynamic-expressions) |
[Binding Syntax](/powersheet/reference/sheet-config/binding-syntax)

<LastReviewed date="2026-06-30" />