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 data 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 data 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 data model YAML (domainModelTypes), not in the sheet configuration. This means they apply consistently across every sheet configuration that uses the same data 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.
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
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
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
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:
| Property | What It Filters | Example Value |
|---|
document.moduleFolder | Restricts to work items within a specific Polarion module folder (space) | Requirements |
document.moduleName | Restricts to work items within a specific document by exact name match | System Specification |
document.type | Restricts to work items in documents of a specific Polarion document type | systemSpecification |
document.component | Restricts by the document’s component property; supports dynamic $context expressions | $context.source.document.component |
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
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 data 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
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 data models per component.
$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 data 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
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:
| Operator | Behavior | Example |
|---|
equals | Exact match (default when no operator specified) | type: systemSpecification |
contains | Substring match | moduleName: { contains: "Spec" } |
in | Matches any value in a list | type: { in: [sysSpec, designSpec] } |
startsWith | Prefix match | moduleFolder: { startsWith: "Req" } |
endsWith | Suffix match | moduleName: { endsWith: "Document" } |
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
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 data 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.
