Skip to main content
This page explains why constraints exist, how the three constraint stages interact through cascading, what properties you can constrain, and how dynamic context expressions enable adaptive filtering at runtime.

​
Why Constraints Exist

Consider a regulated engineering environment: user needs must live in a stakeholder requirements document, system requirements belong in a system specification, and design outputs go into a design document. Polarion itself does not enforce these structural rules — it stores the data, but it does not prevent a user from placing a system requirement in the wrong document or linking a hazard to an unrelated test case. Process constraints in Powersheet act as guardrails: they do not alter what Polarion can store, but they control what Powersheet will display in the sheet, offer in picker dialogs, and permit as a target location when creating new items. Think of constraints as a building’s access control system. The building itself (Polarion) has rooms and hallways connecting them, but the access system (constraints) determines which doors open for which people and which rooms are available for new meetings. The physical structure is unchanged, but the behavior is governed.
Constraints operate at the Powersheet application layer. Users with direct Polarion access can still create or link items outside these rules. Constraints guide correct behavior within the sheet experience; they complement (but do not replace) Polarion workflow rules or link role restrictions.

​
The Three Constraint Stages

The domain model supports three categories of constraints, each operating at a different point in the data lifecycle: diagram

​
Load Constraints

constraints.load filters which entities are retrieved when the sheet initially queries Polarion. This operates at the query level, reducing the result set before data ever reaches the client application. A load constraint typically uses document properties to scope entity retrieval: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          type: systemSpecification
With this constraint, only system requirements residing in documents of type systemSpecification are loaded into the sheet. Items in other document types are invisible to Powersheet, as though they do not exist.

​
Pick Constraints

constraints.pick restricts which existing items appear in picker dialogs when users create or modify relationships. This is critical for preventing incorrect traceability links — without pick constraints, a user could link a system requirement to an item from an unrelated document or project space. 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    constraints:
      pick:
        document:
          moduleFolder: Requirements
          type: needsDocument
When a user opens the picker to select a UserNeed, only items from the Requirements folder in documents of type needsDocument appear as candidates.

​
Create Constraints

constraints.create controls where new work items are placed when users create them through the sheet. By specifying a document constraint with moduleFolder, moduleName, or type, you route new items to the correct location automatically. 
domainModelTypes:
  DesignRequirement:
    polarionType: designOutput
    constraints:
      create:
        document:
          moduleFolder: Design
          type: designSpecification
When a user creates a new DesignRequirement through the sheet, Powersheet automatically places it in a document matching the Design folder and designSpecification type. The user does not need to manually choose a target location.

​
Stage Cascading and Fallback

One of the most important aspects of the constraint system is stage cascading. The three stages form an inheritance chain:
  1. load is the base stage — it stands alone with no inheritance
  2. pick inherits all load constraints (combined with AND logic)
  3. create inherits both load and pick constraints
This cascading behavior means that a single load constraint automatically scopes all three user interactions. If you constrain load to filter by document.type: systemSpecification, then the picker and create dialogs also respect that filter without requiring explicit pick or create blocks.
If no create constraints are explicitly defined for an entity type, the system falls back to using pick constraints for the create stage. This means defining only load and pick is often sufficient — the create behavior inherits from both. However, if you need create to target a different location than what pick allows, you must define create constraints explicitly.
Practical implication: Start with the most restrictive stage you need. If a load constraint covers your needs, you may not need pick or create blocks at all. Add them only when the three stages require different scoping rules.
ScenarioMinimum constraints needed
Same filter for all interactionsload only
Different picker scope than loaded dataload + pick
Create targets a specific documentload + create (or load + pick + create)
Each stage has unique rulesAll three explicitly defined

​
Document-Based Constraint Properties

All three constraint stages share a common set of document-level filter properties:
PropertyDescriptionExample value
document.moduleFolderRestricts to a specific Polarion module folder (space)Requirements
document.moduleNameRestricts to a specific document by exact nameSystem Specification
document.typeRestricts to documents of a specific Polarion document typesystemSpecification
document.idRestricts by full document ID in folder/name formatRequirements/Stakeholder Needs
document.titleRestricts by document display titleStakeholder Requirements
document.componentRestricts by document component; supports $context references$context.source.document.component

​
Comparison Operators

Constraint values are not limited to exact matching. Powersheet provides five comparison operators that give you flexible filtering patterns:
OperatorMeaningExample
equalsExact match (default when no operator specified)type: systemSpecification
containsValue contains the substringmoduleName: {contains: "Spec"}
inValue matches any item in a listtype: {in: [systemSpec, designSpec]}
startsWithValue starts with the prefixmoduleFolder: {startsWith: "Req"}
endsWithValue ends with the suffixmoduleName: {endsWith: "Document"}
When you write a plain string value (like type: systemSpecification), it is interpreted as an equals comparison. Use the object syntax with an explicit operator key when you need other matching behavior.

​
Logical Operators: AND and OR

By default, multiple properties within a document block are combined with AND logic — all conditions must be true for an item to match. 
constraints:
  pick:
    document:
      moduleFolder: Requirements
      type: needsDocument
This means the item must be in the Requirements folder AND in a document of type needsDocument. Powersheet also supports OR logic inside the document block, allowing you to match items that satisfy any one of several conditions. This is useful when valid items can come from multiple document types or folders.
When combining multiple constraints with OR logic, be careful about conflicting conditions. Two constraints that individually match different sets of items may produce an empty result if their intersection is empty. Test complex constraint compositions in a development environment before deploying to production.

​
Dynamic Context References

Constraints support runtime context expressions using the $context prefix. These expressions are resolved dynamically when the constraint is evaluated, allowing the filter to adapt based on the current document or entity. The most common pattern is component-scoped filtering: 
constraints:
  pick:
    document:
      component: $context.source.document.component
This ensures that when a user opens a picker to select a related entity, only items from documents sharing the same component value as the source entity’s document are offered. This is particularly useful in large projects where multiple components (subsystems, variants, or product lines) coexist and traceability must remain within component boundaries. Other available context references include:
ExpressionResolves to
$context.source.document.componentComponent of the source entity’s parent document
$context.document.idFull ID of the current document
The exact set of $context expressions available may vary by Powersheet version. Test context-based constraints in your environment to confirm behavior before relying on them in production configurations.

​
Constraint Composition: A Complete Example

The following domain model excerpt shows constraints applied to a standard RTM hierarchy. Each entity type is scoped to its correct document location, with pick constraints ensuring traceability links stay within the proper boundaries: 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    constraints:
      load:
        document:
          type: stakeholderRequirements
      pick:
        document:
          moduleFolder: Requirements

  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          type: systemSpecification
      create:
        document:
          moduleFolder: Design
          type: systemSpecification

  DesignRequirement:
    polarionType: designOutput
    constraints:
      load:
        document:
          type: designSpecification
      create:
        document:
          moduleFolder: Design
          type: designSpecification

  Hazard:
    polarionType: hazard
    constraints:
      pick:
        document:
          moduleFolder: Risks
          component: $context.source.document.component
In this configuration:
  • UserNeed items are loaded only from stakeholder requirements documents, and pickers further restrict to the Requirements folder
  • SystemRequirement items load from system specifications, and new items are created in the Design folder within system specification documents
  • DesignRequirement follows a similar pattern, scoped to design specifications
  • Hazard pick constraints ensure risk-related linking stays within the same component, enforcing component-level traceability

​
How Constraints Relate to Other Concepts

Constraints work in concert with several other domain model concepts to enforce your engineering process:
  • Link Cardinality controls how many links are allowed between entity types, while constraints control which items are visible, selectable, and creatable
  • Document Rules define broader document-level governance that applies regardless of entity type
  • Entity Types and Relationships define the structural connections that constraints then filter and scope
  • Navigation Properties use the direct and back directions that constraints influence when loading related entities
Together, these mechanisms form a layered governance model: the domain model defines what entities exist and how they relate, cardinality limits the number of connections, and constraints ensure those connections stay within the correct structural boundaries.

​
Common Misconceptions

“Constraints block Polarion from storing data.” They do not. Constraints operate at the Powersheet application layer. A user with direct Polarion access or another tool can still create items outside the constraint boundaries. Constraints govern the Powersheet experience, not the underlying Polarion data store. “I need all three stages defined for every entity type.” In most cases, you only need load constraints. Thanks to cascading, pick inherits from load and create inherits from both. Define additional stages only when their scoping rules differ from the inherited behavior. “OR logic means I can match anything.” While OR broadens the filter, all constraints within a stage are still composed together. Two OR branches with contradictory conditions can still produce an empty result set. Always verify composed constraints against real data. For practical guidance on implementing constraints in your domain model, see Creating Your First Data Model and the Data Model Guides.
KB ArticlesSupport TicketsSource Code
  • DomainModelV2.java
  • EntityTypeFactory.java
  • whole_rtm.template.yaml