Document Filtering - Nextedy Documentation

This reference covers the applyCurrentDocumentTo constraint, document scoping behavior for root and downstream entity types, and how filtering interacts with expansion paths and new entity creation.

Document Filtering Overview

Document filtering is a constraint-based mechanism. When the applyCurrentDocumentTo constraint is defined on a data source, Powersheet automatically restricts results to items that belong to the LiveDoc in which the widget is rendered. The filter operates by matching the document’s moduleFolder and moduleName properties against the current LiveDoc context.

applyCurrentDocumentTo Constraint

The applyCurrentDocumentTo property is defined within the constraints block of a data source configuration. It specifies which entity type should be restricted to only items contained within the current LiveDoc.

Property	Type	Default	Description
`constraints.applyCurrentDocumentTo`	`string`	`null`	Entity type name that should be filtered to only include items belonging to the current document. When the Powersheet widget is rendered inside a LiveDoc, this constraint automatically restricts the named entity type to items within that document.

Use applyCurrentDocumentTo whenever the Powersheet widget is embedded in a LiveDoc and you want the sheet to display only items that belong to that specific document. Without this constraint, the query returns all matching items across the entire project.

Constraint Properties Reference

Property	Type	Default	Description
`constraints`	`object`	`null`	Container for all constraint definitions on a data source.
`constraints.applyCurrentDocumentTo`	`string`	`null`	Entity type name to scope to the current document. Must match a valid entity type in the referenced data model.
`constraints.project`	`string`	See application	Project constraint for filtering. Can use dynamic context labels for resolution.
`constraints.document`	`string`	See application	Document constraint for filtering. Can use dynamic context labels for resolution.

Constraints on entity types combine with constraints defined on relationships. When both an entity type and a relationship define project or document constraints, they are merged with AND logic before query execution.

Root Entity Filtering

When applyCurrentDocumentTo matches the root entity type specified in query.from, the document filter applies directly to the primary query. This is the most common pattern: the sheet displays items of a single type that live in the current document.

sources:
  - id: requirements
    title: System Requirements
    model: rtm
    query:
      from: SystemRequirement
      where: "type = 'UserNeed'"
    constraints:
      applyCurrentDocumentTo: SystemRequirement
    expand:
      - name: designRequirements
        title: Design Requirements
        expand:
          - name: designRequirement

In this configuration:

SystemRequirement is both the root query entity and the document-filtered entity
Only SystemRequirement items that belong to the current LiveDoc are returned
Expanded DesignRequirement items are fetched through the relationship regardless of which document they belong to

How Root Filtering Works

The widget reads the current LiveDoc context (module folder and module name)
The constraint system detects that applyCurrentDocumentTo matches the query.from entity type
A document filter predicate is automatically injected into the query’s where clause
The query returns only items from the specified document

Downstream Entity Filtering

When applyCurrentDocumentTo targets a related entity type (not the root query.from entity), the constraint applies to the downstream entity within the expansion path. The root entity type is queried without document restriction.

sources:
  - id: needs
    title: User Needs
    model: rtm
    query:
      from: UserNeed
      where: "type = 'UserNeed'"
    constraints:
      applyCurrentDocumentTo: SystemRequirement
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: systemRequirement

In this configuration:

UserNeed is the root entity type and is not document-filtered
SystemRequirement is the downstream entity type scoped to the current document
The sheet shows all UserNeed items matching the where clause, but only expands to SystemRequirement items that belong to the current LiveDoc

The entity type name specified in applyCurrentDocumentTo must be a valid entity type defined in the referenced data model. If the entity type is not found, the constraint is silently ignored and no document filtering is applied.

Downstream Filtering Scenarios

Root Entity	Filtered Entity	Behavior
`UserNeed`	`UserNeed`	Root filtering — only `UserNeed` items in current document
`UserNeed`	`SystemRequirement`	Downstream filtering — all `UserNeed` items, but `SystemRequirement` expansion scoped to document
`UserNeed`	`DesignRequirement`	Deep downstream — `UserNeed` and `SystemRequirement` unfiltered, `DesignRequirement` scoped to document
`Hazard`	`RiskControl`	Risk model — all `Hazard` items shown, `RiskControl` expansion scoped to document

Document Context Variables

When document filtering is active, the following context information is available for use within query expressions and dynamic value resolution:

Variable	Description
`document.moduleFolder`	The space (folder) of the current LiveDoc in Polarion (e.g., `Requirements`)
`document.moduleName`	The name of the current LiveDoc (e.g., `SystemRequirements`)
`document.id`	Full document path combining folder and name (e.g., `Requirements/SystemRequirements`)

These variables are automatically populated when the Powersheet widget is rendered inside a LiveDoc. They are used internally by the document filter and are also available via $context.document.id expressions in dynamic value configurations.

The exact format of document.id depends on the Polarion space configuration. For documents in the default space (_default), the space prefix may be omitted from the document ID.

Document Filtering with New Entities

When applyCurrentDocumentTo is configured and a user creates a new entity through the sheet, the document constraint is automatically applied to the new item’s initial values. This ensures newly created items are scoped to the current document without manual intervention.

Behavior	Description
Automatic document assignment	New entities of the type specified in `applyCurrentDocumentTo` receive the current document’s `documentId` as an initial property value
Scope inheritance	The new entity is created within the same LiveDoc context as the current document, maintaining document-centric data integrity
Constraint enforcement	If `applyCurrentDocumentTo` targets the root entity type, new items are automatically assigned to the current document

sources:
  - id: requirements
    title: Requirements
    model: rtm
    query:
      from: SystemRequirement
    constraints:
      applyCurrentDocumentTo: SystemRequirement
    expand:
      - name: designRequirements
        title: Design Requirements
        expand:
          - name: designRequirement

With this configuration, when a user adds a new SystemRequirement through the sheet, it is automatically placed in the current LiveDoc.

Constraint Propagation

Document constraints defined on entity types propagate to related navigation properties during query expansion. This propagation determines how document scoping applies across the full expansion path.

Source	Propagation Rule
Entity type constraints	Extracted from constraint annotations on the entity type
Navigation property constraints	Merged from both the navigation property annotation and the target entity type annotation
Combined result	AND-combined predicate validated against entity type metadata

When both an entity type and its relationship define document constraints, the system merges them. For many-to-many relationships traversed through association types, the constraint resolver unwraps the association to reach the target entity type and applies the combined constraint there.

Data Model Constraint Configuration

Document constraints can also be defined at the entity type level in the data model YAML, independent of the sheet configuration’s applyCurrentDocumentTo. These constraints apply to all queries against the entity type across every sheet configuration that references the model.

domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          moduleFolder: Requirements
          type: requirements_specification
      pick:
        document:
          moduleFolder: Requirements
          moduleName: Categorized

Constraint Level	Purpose	Applied When
`load.document`	Filters entities during initial data loading	Sheet loads data for display
`pick.document`	Filters entities in picker dropdown selections	User opens a relationship picker
`create.document`	Sets default document values for new entities	User creates a new entity through the sheet

Data model constraints (load, pick, create) define static document filters based on known folder or document names. In contrast, applyCurrentDocumentTo is dynamic — it uses the current LiveDoc context at runtime. Both mechanisms can coexist; they are combined with AND logic.

See Constraints for the full constraint configuration reference.

Complete YAML Example

The following example demonstrates a full sheet configuration with document filtering applied to a requirements traceability matrix (RTM):

sources:
  - id: user-needs
    title: User Needs
    model: rtm
    query:
      from: UserNeed
      where: "type = 'UserNeed'"
    constraints:
      applyCurrentDocumentTo: UserNeed
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                title: Design Requirements
                expand:
                  - name: designRequirement

  - id: hazards
    title: Hazards
    model: risk
    query:
      from: Hazard
      where: "type = 'UserNeed'"
    constraints:
      applyCurrentDocumentTo: Hazard
    expand:
      - name: riskControls
        title: Risk Controls
        expand:
          - name: riskControl

columns:
  id:
    width: 80
    sort: asc
  title:
    width: 300
    hasFocus: true
  systemRequirements.systemRequirement.title:
    width: 250
  systemRequirements.systemRequirement.severity:
    width: 100

This configuration defines two data sources:

User Needs source with root-level document filtering on UserNeed and a three-level expansion path: UserNeed > SystemRequirement > DesignRequirement
Hazards source with root-level document filtering on Hazard and a single-level expansion to RiskControl

Both sources restrict their root entity type to items within the current LiveDoc while allowing expanded entities to come from any document.

Interaction with Other Constraints

Document filtering via applyCurrentDocumentTo works alongside other constraint types defined in the data model and sheet configuration:

Constraint Type	Interaction with Document Filtering
Project constraints	Applied independently. Both project and document constraints must be satisfied for an item to appear.
Entity type constraints	Merged with AND logic. Data model constraints on the entity type combine with the document filter.
Relationship constraints	Navigation property constraints on project or document are combined with entity-level constraints when expanding related items.
Security permissions	Checked before any query execution. If the current user lacks read permission (`isReadOnly`) for the entity type, the query is rejected regardless of document filtering.

When both an entity type and its relationship define document constraints, the constraints are combined. Ensure that the constraint definitions do not conflict or create overly restrictive filters that return empty results.

When document filtering targets a downstream entity type, the constraint must be resolved through the expansion path. The system resolves the path from the root entity type to the filtered entity type by traversing navigation properties defined in the data model.

# Data model relationship (direct direction)
relationships:
  - name: systemRequirements
    source: UserNeed
    target: SystemRequirement
    type: manyToMany

For the expansion path UserNeed > systemRequirements > systemRequirement, the constraint resolver:

Starts at the root entity type (UserNeed)
Follows the systemRequirements navigation property (direct direction)
Reaches SystemRequirement and applies the document filter

The resolution supports multi-level dot-notation paths (e.g., systemRequirements.systemRequirement.designRequirements) for deep navigation hierarchies.

Behavior Without Document Context

When the Powersheet widget is rendered outside a LiveDoc context (for example, in a Wiki page or a standalone widget), the document filter has no effect:

Scenario	Behavior
Widget in LiveDoc	`applyCurrentDocumentTo` actively filters by current document
Widget in Wiki page	No document context available; constraint is ignored, all matching items returned
Widget with URL parameters	URL parameters (e.g., `masterItemId`) are applied independently of document filtering

When developing sheet configurations outside a LiveDoc, remember that document filtering is inactive. Validate filtering behavior by embedding the widget in the target LiveDoc.

EntityQuery — query structure and from clause reference
Predicates — where clause predicate syntax
Expand Clause — expansion path configuration
Query Context — context variables and parameter passing
Constraints — data model constraint definitions
Sources — data source configuration reference
Navigation Directions — direct and back relationship traversal

​Document Filtering Overview

​applyCurrentDocumentTo Constraint

​Constraint Properties Reference

​Root Entity Filtering

​How Root Filtering Works

​Downstream Entity Filtering

​Downstream Filtering Scenarios

​Document Context Variables

​Document Filtering with New Entities

​Constraint Propagation

​Data Model Constraint Configuration

​Complete YAML Example

​Interaction with Other Constraints

​Constraint Resolution with Navigation Properties

​Behavior Without Document Context

​Related Pages

Document Filtering Overview

applyCurrentDocumentTo Constraint

Constraint Properties Reference

Root Entity Filtering

How Root Filtering Works

Downstream Entity Filtering

Downstream Filtering Scenarios

Document Context Variables

Document Filtering with New Entities

Constraint Propagation

Data Model Constraint Configuration

Complete YAML Example

Interaction with Other Constraints

Constraint Resolution with Navigation Properties

Behavior Without Document Context

Related Pages