Getting Started: Sources Configuration

Sources are the foundation of your Powersheet configuration. They define what data to load from Polarion and how to navigate relationships between different entity types. Think of sources as the blueprint for your data structure — they specify which entities to query, which related items to include, and how to organize the information in your sheet.

Sources configuration is part of Sheets configuration as described here.

TABLE OF CONTENTS

• When to Use Sources
• Basic Structure
• Source Properties
  • Required Properties
  • Optional Properties
• Query Configuration
  • Basic Query
  • Query with Filtering
  • Query Properties
  • Where Conditions
• Expand Configuration
  • Basic Expansion
  • Expand Properties
  • Multi-Level Expansion
  • Multiple Expansions at Same Level
• Entity Factory
  • Basic Entity Factory
  • Entity Factory in Expansions
• Constraints
  • Apply Current Document Filter

When to Use Sources

Use sources configuration when you need to:

• Query entities from Polarion (requirements, test cases, hazards, etc.)
• Navigate relationships between entities (e.g., show requirements linked to user needs)
• Filter data based on specific criteria (e.g., only items from the current document)
• Set default values for newly created entities
• Create multi-level hierarchies in your sheet (parent-child relationships)

Basic Structure

Sources are defined in your Powersheet YAML configuration under the "sources" key as an array. Each source is a separate data query.

sources:
  - id: "my-source"
    title: User Needs
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

Source Properties

Required Properties

Optional Properties

Query Configuration

The "query" object defines which entities to load from Polarion. It supports OData-style query syntax.

Basic Query

sources:
  - query:
      from: UserNeed

This loads all UserNeed entities from your project.

Query with Filtering

sources:
  - query:
      from: SystemRequirement
      where:
        status:
          in: ["draft", "approved"]

Query Properties

Where Conditions

The where: clause supports various operators:

Equal

where:

  status: "approved"

In (multiple values)

where:

  severity:

    in: ["high", "critical"]

Not equal

where:

  status:

    ne: "obsolete"

Greater than, less than

where:

  priority:

    gt: 3

Combining conditions (AND)

where:

  status: "approved"

  priority:

    gt: 2

Expand Configuration

The expand array lets you include related entities and navigate relationships. This is how you create multi-level sheets showing parent-child relationships.

Basic Expansion

sources:
  - query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

- UserNeed (root level)

  - SystemRequirement (child level via "systemRequirements" relationship)

Expand Properties

Multi-Level Expansion

You can nest expansions to show multiple relationship levels:

sources:
  - query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            title: System Req.
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement
                    title: Design Req.

- UserNeed

  - SystemRequirement

    - DesignRequirement

Multiple Expansions at Same Level

You can expand multiple relationships from the same entity:

sources:
  - query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
      - name: validationTestCases
        expand:
          - name: validationTestCase
      - name: chapter

Entity factories define default values for newly created entities. This is useful for:

• Pre-filling fields based on context
• Setting defaults for document placement
• Ensuring consistency in new items

Basic Entity Factory

sources:
  - query:
      from: UserNeed
    entityFactory:
      status: "draft"
      priority: 3
      documentId: "Requirements/UserNeedSpecification"

When a user creates a new UserNeed, it will automatically have:

• status set to "draft"
• priority set to 3
• documentId set to the specified document path "Requirements/UserNeedSpecification"

Entity Factory in Expansions

You can also define factories for nested entities:

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

Constraints

Constraints provide advanced filtering capabilities, especially useful for document-based filtering and relationship constraints.

Apply Current Document Filter

The "applyCurrentDocumentTo" constraint filters entities to only those belonging to the current Polarion document:

sources:
  - query:
      from: UserNeed
    constraints:
      applyCurrentDocumentTo: UserNeed

This ensures:

• Only UserNeeds from the current document are loaded
• New UserNeeds are automatically created in the current document

You can also apply it to navigation paths:

constraints:
  applyCurrentDocumentTo: systemRequirements.systemRequirement