Constraints in Powersheet

Constraints are filtering rules that determine which Polarion work items are loaded, selectable, and creatable in Powersheet. By defining constraints in your Model or Sheet configuration, you can ensure users only interact with the relevant slice of data. This article covers all available constraint types, stages, operators, and configuration options.

TABLE OF CONTENTS

• What are constraints?
• Configuration of Constraints in the Model
  • Where Constraints Can Be Applied
    • 1. On an entity type: applies to all instances of that type
    • 2. On a relationship navigation property: applies when traversing that relationship:
• Constraint Stages
  • Stage Cascading (Fallback Behavior)
• Constrainable Properties
• Comparison Operators
• Logical Operators (AND / OR)
• Dynamic Constraints with $context
• Constraint Composition (AND Logic)
• Initial Values from Constraints
  • Constraints Quick Reference
• Configuration of Constraints in Sheet
  • Current Document Constraint
• Conclusion

What are constraints?

Constraints define filtering rules that control which Polarion work items are loaded, selectable, and creatable within Powersheet. They can be applied to both entity types (domainModelTypes) and relationships.

Think of constraints as database queries that Powersheet automatically applies behind the scenes; they ensure users only see and interact with the right slice of data.

Configuration of Constraints in the Model

Where Constraints Can Be Applied

Constraints can be placed in two locations:

1. On an entity type: applies to all instances of that type

domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    properties:
      - description
      - severity
    constraints:
      load:
        document:
          type: systemRequirementsSpecification

2. On a relationship navigation property: applies when traversing that relationship:

relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
      constraints:
        load:
          document:
            type: systemRequirementsSpecification

Constraint Stages

Constraints have three stages, each controlling a different user interaction:

Stage Cascading (Fallback Behavior)

Stages cascade upward — more specific stages automatically include constraints from less specific ones:

• Load stage: uses only load constraints
• Pick stage: uses load + pick constraints (combined with AND)
• Create stage: uses load + pick + create constraints (combined with AND)

Fallback rule: If no create constraints are defined, the system automatically uses pick constraints for the create stage instead.

This means that if you only define a load constraint, it will apply everywhere:  during initial load, in pickers, and when creating items.

You only need pick or create constraints when you want additional filtering beyond what load provides.

Example — load + pick constraints:

domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    constraints:
      load:
        document:
          type: systemRequirementsSpecification
      pick:
        document:
           moduleFolder: Requirements 

In this example:

• Initial load: filters by document type only
• Picker dialog: filters by document type AND document module folder
• Create: filters by document type AND document module folder (inherits pick since no create is defined)

Constrainable Properties

Constraints support document navigation properties:

constraints:
  load:
    document:
      type: systemRequirementsSpecification    # document type
      id: Requirements/UserNeedSpecification   # document ID (folder/name)
      moduleName: UserNeedSpecification        # document module name
      moduleFolder: Requirements               # document module folder
      component: Braking                       # document component
      title: My Specification                  # document title

Important limitation: Only document properties are supported for constraints. Filtering by direct work item data properties (like priority, status, etc.) in the constraint query is not supported at this time.

Comparison Operators

By default, a constraint value means equals. You can use comparison operators for more flexible matching:

constraints:
  load:
    document:
      # Exact match (default)
      type: systemRequirementsSpecification

      # Contains
      moduleName:
        contains: Specification

      # In (match any value in a list)
      type:
        in: [systemRequirementsSpecification, designRequirementsSpecification]

      # Starts with
      title:
        startsWith: REQ-

      # Ends with
      title:
        endsWith: -Draft

Logical Operators (AND / OR)

You can use and and or operators inside navigation properties for complex filtering.

• Load items from document "Alpha" OR document "Beta":

constraints:
  load:
    document:
      or:
        - moduleName: Alpha
        - moduleName: Beta

• Load items from documents whose name contains "Spec" AND are in the "Requirements" folder

constraints:
  load:
    document:
      moduleName:
        contains: Spec
      moduleFolder: Requirements

Important rule: The document filter must always be at the top level of the constraint. You can put or/and logic inside it, but you cannot wrap document: inside an or: block.

✅ This works:

document:
  or:
    - moduleName: DocA
    - moduleName: DocB

❌ This does NOT work:

# Invalid — document is inside or, not at top level
or:
  - document:
      moduleName: DocA
  - document:
      moduleName: DocB

Dynamic Constraints with $context

Constraints can reference values from the current context using the $context syntax. This is particularly useful for relationship constraints where you want downstream items to be filtered based on the upstream item's properties.

relationships:
  - from: DesignRequirement
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: systemRequirements
    back:
      name: designRequirements
      constraints:
        load:
          document:
            component: $context.source.document.component

Available context paths:

Dynamic constraints are evaluated at runtime for each row, so different rows can have different constraint values based on their individual context.

Constraint Composition (AND Logic)

When constraints are defined at multiple levels, such as on an entity type and a relationship, or combined with the sheet-level applyCurrentDocumentTo constraint, they are automatically combined using AND logic.

All constraints must be satisfied simultaneously.

Example:

domainModelTypes:
  SystemRequirement:
    polarionType: sys_req
    constraints:
      load:
        document:
          type: systemRequirementsSpecification

relationships:
  - from: DesignRequirement
    to: SystemRequirement
    back:
      name: designRequirements
      constraints:
        load:
          document:
            moduleName:
              contains: Alpha

When loading SystemRequirements through this relationship, the effective constraint is:

document.type = systemRequirementsSpecification  AND  document.moduleName contains "Alpha"

Watch out for conflicts: If entity-level and relationship-level constraints specify incompatible values for the same property (e.g., document.type = A and document.type = B), the AND composition will result in no matching items — this is expected behavior, not an error. Powersheet does not warn about conflicting constraints.

Initial Values from Constraints

When a user creates a new work item, Powersheet automatically uses constraint values as initial defaults. 

For example, if a load constraint specifies document.type: systemRequirementsSpecification, newly created items will be automatically assigned to a document of that type.

This ensures new items are always created within the scope defined by the constraints.

Constraints Quick Reference

Configuration of Constraints in Sheet

Current Document Constraint

This is a special client-side constraint for filtering entities by the currently open document.
It is configured in the sheet configuration using the applyCurrentDocumentTo property under the sources.constraints section.

It accepts:

• An entity type name
• A navigation path (e.g., systemRequirements.systemRequirement.designRequirements) — not supported yet

It is disabled by default.

Example:

source:
  query:
    from: UserNeed
  constraints:
    applyCurrentDocumentTo: UserNeed