Constraints - Nextedy Documentation

Constraint Stages Overview

Powersheet supports three constraint stages, each applied at a different point in the entity lifecycle:

Stage	Purpose	When Applied
`load`	Filters which entities are loaded and displayed in the sheet	At query/load time
`pick`	Filters which entities appear in selection dropdowns (pickers)	When opening a picker dialog
`create`	Specifies default values for newly created entities	At entity creation time

Stage Cascading

Constraint stages cascade upward — more specific stages inherit all constraints from less specific ones, combined with AND logic:

Load stage: applies only load constraints
Pick stage: applies load + pick constraints (AND)
Create stage: applies load + pick + create constraints (AND)

If no create constraints are defined, the system automatically uses pick constraints for the create stage. This means defining pick constraints also affects item creation unless explicit create constraints override them.

Because load constraints propagate to all subsequent stages, a load constraint that restricts entities to a specific document will also restrict picker results and creation scope. You only need to define more specific constraints when pick or create require additional filtering beyond what load already provides.

Constraint Properties Reference

Top-Level Structure

Name	Type	Default	Description
`constraints`	`object`	None	Top-level constraint container for an entity type. Contains `load`, `create`, and/or `pick` sub-objects. Defined within a `domainModelTypes` entry.
`constraints.load`	`object`	None	Query constraint defining which entities to load from Polarion. Filters entities based on document properties, work item fields, or other criteria.
`constraints.pick`	`object`	None	Picker constraint filtering which entities appear in selection dropdowns when creating or editing relationships. Inherits `load` constraints via cascading.
`constraints.create`	`object`	None	Creation constraint specifying initial values or scope for newly created entities. Inherits both `load` and `pick` constraints via cascading.

Document Constraint Properties

Each constraint stage accepts a document object for document-based filtering. These properties scope entities to specific Polarion LiveDoc documents. All standard document metadata fields are constrainable.

Name	Type	Default	Description
`document`	`object`	None	Document-based constraint object. Scopes entities to work items within specific LiveDoc documents.
`document.moduleFolder`	`string`	None	Polarion space (module folder) containing the document, e.g., `"Requirements"` or `"Risks"`. Supports comparison operators.
`document.moduleName`	`string`	None	Polarion document name (module name) within the space. Supports comparison operators.
`document.type`	`string`	None	Document type identifier (e.g., `req_specification`, `risk_analysis`). Supports comparison operators.
`document.id`	`string`	None	Polarion document ID to constrain entities to. Matches the document’s internal identifier (e.g., `"Requirements"`). Supports comparison operators.
`document.title`	`string`	None	Polarion document title to constrain entities to. Matches the document’s display title. Supports comparison operators.
`document.component`	`string`	None	Component or category assigned to the document. Useful for scoping by product component or sub-system. Supports comparison operators.

All document metadata fields — moduleFolder, moduleName, type, id, title, and component — can be used in constraint expressions. Combine them within a single document block to express precise scoping rules (for example, constraining by space and document type together).

Field-Level Constraint Properties

In addition to document constraints, each stage can constrain on work item field values:

Name	Type	Default	Description
`<fieldName>`	`string` or `object`	None	Constrains the named work item field to a specific value or comparison expression. The field name must match a property defined on the entity type or a built-in Polarion field.

Comparison Operators

Constraint values support five comparison operators for flexible matching:

Operator	Syntax	Description	Example
`equals`	`value` or `{ equals: value }`	Exact match (default when a plain string is provided)	`severity: high`
`contains`	`{ contains: value }`	Substring match — true if the field value contains the specified text	`title: { contains: "safety" }`
`in`	`{ in: [v1, v2, ...] }`	Set membership — true if the field value matches any item in the list	`status: { in: [approved, reviewed] }`
`startsWith`	`{ startsWith: value }`	Prefix match — true if the field value starts with the specified text	`id: { startsWith: "REQ-" }`
`endsWith`	`{ endsWith: value }`	Suffix match — true if the field value ends with the specified text	`title: { endsWith: "-draft" }`

When a constraint value is a plain string (not an object), it is treated as an equals comparison. Use the object syntax only when you need a different operator.

Logical Operators

AND Logic (Between Constraints)

Multiple constraints within the same stage are combined with AND logic. All conditions must be true for an entity to pass the constraint:

domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    constraints:
      load:
        severity: high
        status: approved
        # Result: severity = "high" AND status = "approved"

OR Logic (Within Document Block)

Inside the document block, OR logic is supported. An entity passes the constraint if it matches any of the document conditions:

domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    constraints:
      load:
        document:
          id:
            in: [Requirements, SafetyRequirements]
        # Result: document.id = "Requirements" OR document.id = "SafetyRequirements"

Field-level constraints use AND logic between each other, while the in operator provides OR semantics within a single field. This combination covers most practical filtering scenarios.

Dynamic Context Constraints

Constraints can reference the current runtime context using special context expressions. This enables constraints that are resolved dynamically based on the active sheet session.

Context Variable	Description
`$currentDocument.id`	ID of the document currently open in the Polarion LiveDoc
`$currentDocument.title`	Title of the currently open document

domainModelTypes:
  UserNeed:
    polarionType: user_need
    constraints:
      load:
        document:
          id: $currentDocument.id
      pick:
        document:
          id: $currentDocument.id

This configuration ensures that only work items from the currently viewed document are loaded into the sheet and shown in pickers.

The full list of available context variables may extend beyond $currentDocument. Consult the application release notes for the latest supported context expressions.

For more on context expressions in queries, see Context Expressions Reference.

Constraint Composition

Constraints can be defined at multiple stages simultaneously on the same entity type. When combined, stages cascade as described above.

Composition Example

domainModelTypes:
  DesignRequirement:
    polarionType: des_req
    constraints:
      load:
        document:
          id: $currentDocument.id
      pick:
        status:
          in: [approved, reviewed]
      create:
        severity: medium

Effective constraints at each stage:

Stage	Effective Constraints
Load	`document.id = $currentDocument.id`
Pick	`document.id = $currentDocument.id` AND `status IN [approved, reviewed]`
Create	`document.id = $currentDocument.id` AND `status IN [approved, reviewed]` AND `severity = medium`

Constraint composition can produce empty results if constraints conflict. For example, a load constraint limiting entities to status: approved combined with a pick constraint for status: draft would produce no picker results because both conditions apply simultaneously (AND logic). Review your cascading chain to avoid contradictions.

Complete YAML Examples

Load-Only Constraint

Restrict an entity type to only show work items from a specific document:

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
    constraints:
      load:
        document:
          id: Requirements

Effect: Only UserNeed items in the “Requirements” document are loaded into the sheet. Pickers and creation inherit this constraint.

Pick-Only Constraint

Allow all entities to load but restrict picker options:

domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:
    constraints:
      pick:
        status:
          in: [approved, reviewed]

Effect: All SystemRequirement items load normally. Picker dialogs only show items with status approved or reviewed. Since no create constraints are defined, the pick constraints apply as a fallback during creation as well.

Create-Only Constraint

Set default values when creating new entities without affecting loading or picking:

domainModelTypes:
  Hazard:
    polarionType: hazard
    properties:
      severity:
      status:
    constraints:
      create:
        severity: low
        status: draft

Effect: All hazards load normally and all appear in pickers. Newly created hazards default to severity: low and status: draft.

Current-Document Scoping

Dynamically scope all stages to the currently open document:

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
    constraints:
      load:
        document:
          id: $currentDocument.id
      pick:
        document:
          id: $currentDocument.id
      create:
        document:
          id: $currentDocument.id

Effect: Loading, picking, and creation are all scoped to the document currently open in Polarion. This is the most common pattern for document-centric sheets.

Multi-Stage Composition

A complete example combining all three stages with different scoping:

domainModelTypes:
  Chapter:
    polarionType: heading

  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:
    constraints:
      load:
        document:
          id: $currentDocument.id
      pick:
        status:
          in: [approved, reviewed, draft]
      create:
        severity: medium

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:
    constraints:
      load:
        document:
          id: $currentDocument.id
      pick:
        severity:
          in: [high, critical]

relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

Effect:

UserNeed items load from the current document, pickers show only approved/reviewed/draft items from that document, and new items default to severity: medium
SystemRequirement items load from the current document, pickers show only high/critical severity items from that document
The relationships section connects the two entity types — picker constraints on UserNeed affect which items appear when linking a SystemRequirement to user needs

Constraints and Relationships

Constraints interact with Relationships through picker behavior. When a sheet column binds to a navigation property (e.g., userNeeds or chapter), the picker dialog for that column uses the pick constraints defined on the target entity type.

Relationship	Column Binding	Picker Constrained By
`SystemRequirement` -> `UserNeed`	`userNeeds`	`UserNeed.constraints.pick`
`UserNeed` -> `Chapter`	`chapter`	`Chapter.constraints.pick`

For details on how cardinality affects column bindings, see Cardinality. For details on column binding syntax, see Binding Syntax.

If a picker shows too many or too few items when linking entities, check the pick constraints on the target entity type. Remember that load constraints cascade into pick, so an overly restrictive load constraint will also limit picker results.

Sheet-Level Constraints

In addition to data model constraints, constraints can also be applied at the sheet configuration level through source queries. Source-level constraints use the query and expand syntax rather than the constraints YAML key.

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

Source-level filtering and data model constraints work together:

Data model constraints (this page) define permanent scoping rules for an entity type across all sheets
Source query constraints restrict which entities appear in a specific sheet configuration

For source query syntax, see Sources. For query filtering options, see EntityQuery and Document Filtering.

Quick Reference

Constraint Stage Summary

Stage	Inherits From	Purpose	Fallback
`load`	—	Filter entities at query time	None
`pick`	`load`	Filter picker dropdown items	None
`create`	`load` + `pick`	Set defaults on new entities	Falls back to `pick` if undefined

Operator Summary

Operator	Syntax	Logic
`equals`	`field: value`	Exact match
`contains`	`field: { contains: value }`	Substring
`in`	`field: { in: [a, b] }`	Any match (OR)
`startsWith`	`field: { startsWith: value }`	Prefix
`endsWith`	`field: { endsWith: value }`	Suffix

Cascading Rules

Rule	Behavior
Multiple fields in one stage	AND logic
`in` operator values	OR logic (within single field)
Cross-stage inheritance	AND with parent stage constraints
Missing `create` stage	Falls back to `pick` constraints
Conflicting constraints	May produce empty result set

​Constraint Stages Overview

​Stage Cascading

​Constraint Properties Reference

​Top-Level Structure

​Document Constraint Properties

​Field-Level Constraint Properties

​Comparison Operators

​Logical Operators

​AND Logic (Between Constraints)

​OR Logic (Within Document Block)

​Dynamic Context Constraints

​Constraint Composition

​Composition Example

​Complete YAML Examples

​Load-Only Constraint

​Pick-Only Constraint

​Create-Only Constraint

​Current-Document Scoping

​Multi-Stage Composition

​Constraints and Relationships

​Sheet-Level Constraints

​Quick Reference

​Constraint Stage Summary

​Operator Summary

​Cascading Rules

Constraint Stages Overview

Stage Cascading

Constraint Properties Reference

Top-Level Structure

Document Constraint Properties

Field-Level Constraint Properties

Comparison Operators

Logical Operators

AND Logic (Between Constraints)

OR Logic (Within Document Block)

Dynamic Context Constraints

Constraint Composition

Composition Example

Complete YAML Examples

Load-Only Constraint

Pick-Only Constraint

Create-Only Constraint

Current-Document Scoping

Multi-Stage Composition

Constraints and Relationships

Sheet-Level Constraints

Quick Reference

Constraint Stage Summary

Operator Summary

Cascading Rules