Skip to main content

​
Why Constraints Exist

Imagine a warehouse where any box can be placed on any shelf. That is how Polarion’s native data model works: any work item can link to any other work item, reside in any document, and be created anywhere. This flexibility is powerful but can lead to structural chaos in regulated environments where requirements must live in specific documents, risks must trace to specific controls, and design outputs must stay within their designated spaces. Process constraints in Powersheet act as guardrails: they do not change what Polarion can store, but they control what Powersheet will display, allow users to pick, and where it permits new items to be created.

​
The Three Constraint Types

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 reaches the client. A load constraint typically uses document properties to scope the data: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          type: systemSpecification
This ensures only system requirements from documents of type systemSpecification appear in the sheet.

​
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 document automatically. 
domainModelTypes:
  DesignRequirement:
    polarionType: designOutput
    constraints:
      create:
        document:
          moduleFolder: Design
          type: designSpecification

​
Pick Constraints

constraints.pick restricts which existing items appear in picker dialogs when users create relationships. This is critical for preventing incorrect traceability links. 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    constraints:
      pick:
        document:
          moduleFolder: Requirements
          type: needsDocument

​
Document-Based Constraint Properties

All three constraint types share a common set of document-based filter properties:
PropertyDescription
document.moduleFolderRestricts to a specific Polarion module folder (space)
document.moduleNameRestricts to a specific document by exact name
document.typeRestricts to documents of a specific Polarion document type
document.componentRestricts by document component; supports $context references
Load constraints defined on an entity type propagate to that entity type’s navigation properties in the metadata. This means if you set a load constraint on SystemRequirement, it also affects how SystemRequirement.document navigation behaves. Pick and create constraints do not propagate.

​
Dynamic Context References

Constraints support runtime context expressions using the $context prefix. The most common pattern is $context.source.document.component, which dynamically resolves to the component of the source entity’s document: 
constraints:
  pick:
    document:
      component: $context.source.document.component
This ensures that when a user picks a related entity, only items from documents with the same component value are offered.
The exact set of $context expressions available may vary by version. Test context-based constraints in your environment to confirm behavior.

​
How Constraints Relate to Other Concepts

Constraints work in concert with Link Cardinality and Document Rules to enforce your engineering process. While cardinality controls how many links are allowed, constraints control which items are visible, selectable, and creatable. For practical setup guidance, see Creating Your First Data Model.
Source Code
  • todos_model.yaml
  • todosBig_model.yaml
  • model.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints-base.yaml
  • DatabridgeMetadata.java