Prerequisites
- A working domain model with entity types and relationships already defined
- At least one relationship with
direct and back navigation properties configured
- Familiarity with the three constraint stages (
load, pick, create) covered in Configure Constraints
How Context Expressions Work
A context expression uses the $context prefix followed by a dot-notation property path. Powersheet resolves this path at runtime by reading the current row’s source entity properties. Unlike static constraint values, context expressions produce different filter results per row depending on each source entity’s document.
Context expressions ($context.property.path) are used only in domain model YAML — specifically inside constraints blocks. They support dot-notation property access but not JavaScript logic. For dynamic expressions in sheet configuration YAML (sources, columns, formatters), use the () => expression syntax instead. See Configure Dynamic Expressions for that approach. Available Context Paths
The $context object provides access to the source entity’s document properties. These are the paths you can use:
| Path | Description | Example Value |
|---|
$context.source.type | Source entity’s work item type | "sys_req" |
$context.source.document.id | Source entity’s document ID | "Requirements/SRS" |
$context.source.document.moduleName | Source entity’s document module name | "UserNeedSpecification" |
$context.source.document.moduleFolder | Source entity’s document folder | "Requirements" |
$context.source.document.component | Source entity’s document component | "Braking" |
$context.source.document.type | Source entity’s document type | "systemRequirementsSpecification" |
$context.source.document.title | Source entity’s document title | "System Requirements" |
Step 1: Filter by Document Component
The most common use case is scoping relationship pickers by the source entity’s document component. This prevents users from accidentally linking to entities outside their subsystem.
Add a $context reference inside the constraint document block on the appropriate relationship direction:
relationships:
- from: DesignRequirement
to: SystemRequirement
cardinality: many-to-many
storage: linkedWorkItems
linkRole: satisfies
direct:
name: systemRequirements
back:
name: designRequirements
constraints:
load:
document:
component: $context.source.document.component
SystemRequirement in a document with component “Braking”, only DesignRequirement items from “Braking” documents will be loaded as children.
Step 2: Filter by Document Name and Folder
To restrict linked items to the exact same document as the source entity, combine moduleName and moduleFolder:
constraints:
load:
document:
moduleName: $context.source.document.moduleName
moduleFolder: $context.source.document.moduleFolder
Step 3: Apply Context Constraints to Pick and Create Stages
Context expressions work across all three constraint stages. Apply them to pick to scope the relationship picker dialog, or to create to control where new items are created:
relationships:
- from: Hazard
to: UserNeed
cardinality: many-to-many
storage: linkedWorkItems
linkRole: mitigates
direct:
name: userNeeds
back:
name: hazards
constraints:
load:
document:
component: $context.source.document.component
pick:
document:
type: $context.source.document.type
create:
document:
moduleFolder: $context.source.document.moduleFolder
- load: only hazards from the same component appear in the sheet
- pick: the picker shows items from documents of the same type as the source
- create: new hazards are created in the same folder as the source document
The same cascading rules apply to context constraints as to static constraints. The pick stage inherits load constraints, and create inherits both load and pick. You only need to define the additional filter at each stage.
Step 4: Apply Context Constraints at Entity Type Level
Context expressions can also be placed on domainModelTypes entries (not just relationships). This applies the constraint globally whenever that entity type is loaded, picked, or created:
domainModelTypes:
SystemRequirement:
polarionType: sys_req
properties:
description:
severity:
constraints:
pick:
document:
component: $context.source.document.component
When both the entity type and a relationship define constraints, both are applied. If they conflict (for example, the entity constraint specifies one component and the relationship constraint specifies a different filter), the intersection may produce an empty result set. Place context constraints at either the entity type or the relationship level, not both, unless you intentionally need combined filtering.
Step 5: Combine Context and Static Constraints
You can mix $context expressions with static values in the same constraint block. Static values act as fixed filters while context values adapt per row:
constraints:
pick:
document:
type: systemRequirementsSpecification
component: $context.source.document.component
systemRequirementsSpecification documents and in the same component as the source entity’s document.
Common Patterns
| Scenario | Context Path | Constraint Example |
|---|
| Same component | $context.source.document.component | component: $context.source.document.component |
| Same document | $context.source.document.moduleName | moduleName: $context.source.document.moduleName |
| Same folder | $context.source.document.moduleFolder | moduleFolder: $context.source.document.moduleFolder |
| Same document type | $context.source.document.type | type: $context.source.document.type |
| Same document (exact) | $context.source.document.id | id: $context.source.document.id |
Complete YAML Example
Below is a full domain model snippet demonstrating context constraints across entity types and relationships in a standard RTM hierarchy:
domainModelTypes:
UserNeed:
polarionType: user_need
properties:
description:
severity:
SystemRequirement:
polarionType: sys_req
properties:
description:
severity:
DesignRequirement:
polarionType: des_req
properties:
description:
RiskControl:
polarionType: risk_control
properties:
description:
relationships:
- from: SystemRequirement
to: UserNeed
cardinality: many-to-many
storage: linkedWorkItems
linkRole: decomposes
direct:
name: userNeeds
back:
name: systemRequirements
constraints:
load:
document:
component: $context.source.document.component
pick:
document:
component: $context.source.document.component
type: systemRequirementsSpecification
- from: DesignRequirement
to: SystemRequirement
cardinality: many-to-many
storage: linkedWorkItems
linkRole: satisfies
direct:
name: systemRequirements
back:
name: designRequirements
constraints:
load:
document:
component: $context.source.document.component
- from: RiskControl
to: DesignRequirement
cardinality: many-to-many
storage: linkedWorkItems
linkRole: mitigates
direct:
name: designRequirements
constraints:
pick:
document:
moduleFolder: $context.source.document.moduleFolder
back:
name: riskControls
Verification
After saving the domain model with context constraints:
- Open a sheet that uses this domain model
- Navigate to a row whose source entity belongs to a specific document component (e.g., “Braking”)
- For load constraints: verify that child rows show only entities from the same component
- For pick constraints: click a relationship picker cell and confirm the dropdown shows only items matching the source entity’s document properties
- Compare two rows from different components — each should show different filtered results based on its own source entity context
You should now see context-sensitive filtering where each row’s constraints resolve independently based on its source entity’s document properties. If all rows show the same results regardless of component, verify that:
- The
$context path is spelled correctly (case-sensitive)
- Source entities actually have different document component/folder values in Polarion
- The constraint is placed on the correct relationship direction (
direct or back)
If a source entity’s document has no component value set in Polarion, a constraint using $context.source.document.component will resolve to an empty string, which typically matches no items. Ensure your Polarion documents have the relevant properties populated before relying on context constraints.
See Also
