Skip to main content
Think of document rules as a filing system for a regulated office: each type of document has its designated drawer, and the rules ensure that nobody accidentally files a safety hazard report in the requirements drawer. Polarion itself does not enforce this discipline — Powersheet adds it through the domain model’s constraint mechanism.

​
Why Document Rules Matter

Siemens Polarion ALM organizes work items inside LiveDoc documents, but it does not natively restrict which work item types belong in which documents. A systemRequirement work item can be created in any document, and a userNeed can end up in a design specification. In regulated industries following standards like ISO 26262 or Automotive SPICE, this structural freedom introduces risk: auditors expect clear separation between requirement types, and traceability gaps emerge when items scatter across uncontrolled locations. Document rules in the domain model act as process guardrails. They do not alter Polarion’s underlying data storage — they control what Powersheet queries, displays, and permits through the sheet interface. This distinction is important: a SystemRequirement work item that exists in an unexpected document is not deleted or moved by a document rule. Instead, the rule simply prevents it from appearing in the sheet, being selected in a picker, or being the default location for new items of that type.
Document rules are defined per entity type in the domain model YAML (domainModelTypes), not in the sheet configuration. This means they apply consistently across every sheet configuration that uses the same domain model, regardless of column layout or view settings.

​
The Three Constraint Stages

Document rules operate through three constraint stages, each controlling a different aspect of how entities interact with documents. These stages are defined within the constraints block on an entity type. diagram

​
Stage Cascading

A critical concept is that constraint stages cascade upward:
  • pick inherits from load. If you define load constraints but no pick constraints, the pick stage uses the load constraints automatically.
  • create inherits from both load and pick. If no explicit create constraints exist, the system falls back to pick constraints (which themselves may have fallen back to load).
This cascading means you often only need to define the load stage. The pick and create stages will inherit its document rules unless you need different behavior at those stages.
The fallback chain is: create -> pick -> load. If you define only load document rules, all three stages use them. If you define load and pick, the create stage inherits from pick (not load). Define explicit create constraints only when new items should go to a different location than where picker results come from.

​
Load Stage

A load constraint with document rules filters the initial data query so that only work items residing in matching documents appear in the sheet: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          type: systemSpecification
This ensures the sheet query only returns SystemRequirement items from documents whose type is systemSpecification. Items of the same Polarion work item type in other documents are excluded from the display.

​
Pick Stage

Pick constraints scope the item picker dialog. When a user links a relationship to a UserNeed, the picker shows only items matching the pick constraints: 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    constraints:
      pick:
        document:
          moduleFolder: Requirements
          type: needsDocument
When another entity type references UserNeed through a relationship, the picker dialog will only show user needs from needsDocument-type documents in the Requirements folder. This prevents users from accidentally linking to items in unrelated documents.

​
Create Stage

Create constraints determine the default document location when a user creates a new entity through the sheet: 
domainModelTypes:
  DesignRequirement:
    polarionType: designOutput
    constraints:
      create:
        document:
          moduleFolder: Design
          moduleName: Design Specification
When a user creates a new DesignRequirement item, Powersheet automatically places it in the Design Specification document within the Design folder. Without this constraint, new items might be created in the currently active document, which may not be the intended location.

​
Document Filter Properties

All three constraint stages support the same set of document filter properties within the document block:
PropertyWhat It FiltersExample Value
document.moduleFolderRestricts to work items within a specific Polarion module folder (space)Requirements
document.moduleNameRestricts to work items within a specific document by exact name matchSystem Specification
document.typeRestricts to work items in documents of a specific Polarion document typesystemSpecification
document.componentRestricts by the document’s component property; supports dynamic $context expressions$context.source.document.component
These properties can be combined within a single document block. When multiple properties are specified, they act as an AND condition — all criteria must match for a document to qualify. 
constraints:
  load:
    document:
      moduleFolder: Requirements
      type: systemSpecification
      component: Braking
This loads only systemSpecification-type documents from the Requirements folder that belong to the Braking component.

​
Dynamic Document Scoping with Context

For projects where document assignments vary by component, subsystem, or other runtime context, document rules support $context expressions. These expressions resolve dynamically based on the current document, source entity, or query parameters rather than being hardcoded in the domain model. The most common pattern scopes constraints to the same component as the source entity’s document: 
constraints:
  pick:
    document:
      component: $context.source.document.component
This ensures that when picking related items, only entities from documents with the same component value as the source entity’s document are shown. In multi-component projects — where each component has its own requirement, design, and test documents — this prevents cross-component linking mistakes.
Use $context.source.document.component when your project structure mirrors a component hierarchy. For example, if the Braking subsystem has its own System Specification and Design Specification documents, dynamic scoping ensures that requirements in the Braking specification only link to design items in the Braking design document — without needing separate entity types or domain models per component.
The query manager resolves $context expressions at runtime by injecting the current document’s properties (such as document.id, document.moduleFolder, and document.component) into the query parameters. This resolution happens transparently before the query is sent to the server.

​
Combining Document Rules Across Entity Types

In a full RTM domain model, each entity type typically has its own document rules. Consider a standard requirements traceability hierarchy: 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    constraints:
      load:
        document:
          type: needsDocument
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          type: systemSpecification
  DesignRequirement:
    polarionType: designOutput
    constraints:
      load:
        document:
          type: designSpecification
      create:
        document:
          moduleFolder: Design
          moduleName: Design Specification
  Hazard:
    polarionType: hazard
    constraints:
      pick:
        document:
          component: $context.source.document.component
Each entity type is scoped to its appropriate document type. The DesignRequirement type adds an explicit create stage to control where new items land. The Hazard type uses dynamic component scoping for its picker.

​
Comparison Operators in Constraints

Beyond simple equality matching, constraints support several comparison operators that provide more flexible filtering:
OperatorBehaviorExample
equalsExact match (default when no operator specified)type: systemSpecification
containsSubstring matchmoduleName: { contains: "Spec" }
inMatches any value in a listtype: { in: [sysSpec, designSpec] }
startsWithPrefix matchmoduleFolder: { startsWith: "Req" }
endsWithSuffix matchmoduleName: { endsWith: "Document" }
These operators are useful when document naming follows a pattern rather than exact conventions, or when a single constraint needs to match multiple document types.

​
Logical Operators

Within the document block, constraints support OR logic for combining alternative conditions. Multiple criteria at the same level are joined with AND logic by default. To express OR conditions, the constraint system allows alternative document blocks: 
constraints:
  pick:
    document:
      moduleFolder: Requirements
      type: needsDocument
All properties within the same document block are evaluated as AND. If no create constraints are defined, the system falls back to pick constraints for the create stage, ensuring consistent behavior without redundant configuration.
When composing multiple constraints, be careful that the combined conditions do not produce an empty result set. For example, constraining to moduleFolder: Design AND type: needsDocument might match no documents if your needs documents reside in the Requirements folder. Test constraint combinations by checking what the picker shows before committing the configuration.

​
Common Misconceptions

“Document rules move work items between documents.” They do not. Document rules only affect what Powersheet loads, displays in pickers, and uses as the target for new items. A work item’s actual document location in Polarion is unchanged by document rules. “I need to define all three stages.” Due to cascading inheritance, defining only the load stage is often sufficient. The pick and create stages inherit from it automatically. Define separate stages only when you need different behavior — for example, loading broadly but creating in a specific document. “Document rules replace Polarion permissions.” Document rules are a domain model concern, not a security mechanism. They guide the sheet interface but do not override Polarion’s native permission model. A user with Polarion permissions to edit a document outside the constraint scope could still modify items through Polarion’s standard interface, just not through Powersheet.

​
Relationship to Other Concepts

Document rules are one layer of the broader constraint system in Powersheet. They work alongside other concepts to create a complete enforcement model:
  • Process Constraints define validation rules beyond document scoping, such as field-level restrictions and workflow enforcement.
  • Link Cardinality controls how many relationships of a given type are permitted — while document rules control where the related entities can come from.
  • Entity Types and Relationships define the structural foundation that document rules operate upon.
  • Navigation Properties determine how relationships are traversed; document rules determine which items are reachable during that traversal.
For practical setup instructions, see the Data Model Guides. For the full constraint property reference, see the Data Model Reference.
Tickets
  • Constraints KB article creation (ticket covering constraint stages, cascading, comparison operators)
  • Data model configuration guidance requests
Source Code
  • PowersheetDocumentConfigurationService.java
  • QueryManager.tsx
  • DomainModelV2.java
  • EntityTypeFactory.java