Skip to main content
diagram

​
Context Object Structure

The context object is a hierarchical namespace that Powersheet populates at runtime. Different properties become available depending on where the expression is evaluated. 
context
+-- parameters          URL and configuration parameters (key-value pairs)
|   +-- {paramName}     e.g. context.parameters.client
+-- user                Current logged-in user
|   +-- id, name
+-- sources             All configured data source definitions
+-- document            Current document information
|   +-- title, type, id, moduleName, moduleFolder, component
+-- tool                Current tool information
|   +-- type
+-- item                Current entity (available in per-cell contexts)
|   +-- {propertyName}  e.g. context.item.StoryPoints
+-- source              Parent/source entity (in relationship contexts)
|   +-- {propertyName}  e.g. context.source.document.component
+-- entity              Current entity as a plain object
+-- value               Current cell's display value

​
Context Properties Reference

PropertyTypeDescription
context.parametersobjectKey-value map of URL query parameters and configuration-injected parameters
context.parameters.{name}stringIndividual parameter accessed by name (e.g., context.parameters.client)
context.userobjectCurrent authenticated Polarion user
context.user.idstringPolarion user ID
context.user.namestringDisplay name of the current user
context.sourcesobjectAll configured data source definitions from the sheet configuration
context.documentobjectCurrent Polarion LiveDoc document metadata
context.document.titlestringDocument title
context.document.typestringDocument type identifier
context.document.idstringFull document path in folder/name format
context.document.moduleNamestringDocument module name
context.document.moduleFolderstringDocument folder path
context.document.componentstringDocument component (e.g., "Braking")
context.toolobjectCurrent tool information
context.tool.typestringTool type identifier
context.itemobjectCurrent row entity with all properties accessible by name
context.item.{propertyName}variesAny property of the current entity (e.g., context.item.StoryPoints, context.item.Probability)
context.sourceobjectParent/source entity in relationship navigation contexts
context.entityobjectCurrent entity as a plain JavaScript object
context.valuevariesCurrent cell’s resolved display value

​
Two Expression Notations

Powersheet uses two distinct notations for dynamic expressions, each tied to a specific configuration context.
NotationSyntaxUsed In
Context expression$context.property.pathDomain model configuration (constraints)
Dynamic value() => expressionSheet configuration (where, formula, render, formatter, display)
If you are editing a domain model YAML file (domainModelTypes, relationships), use $context. If you are editing a sheet configuration YAML file (sources, columns, formatters), use () =>.

​
Context Expression ($context)

Context expressions use dot-notation to access properties from the runtime context. They are used exclusively in domain model constraint definitions. No JavaScript logic is supported --- only direct property access. Where it is used:
  • domainModelTypes.*.constraints --- entity type constraints
  • relationships.*.direct.constraints / relationships.*.back.constraints --- relationship constraints
Available $context paths:
PathDescriptionExample Value
$context.source.typeSource entity’s work item type"sys_req"
$context.source.document.idSource entity’s document ID"Requirements/SRS"
$context.source.document.moduleNameSource entity’s document module name"UserNeedSpecification"
$context.source.document.moduleFolderSource entity’s document folder"Requirements"
$context.source.document.componentSource entity’s document component"Braking"
$context.source.document.typeSource entity’s document type"systemRequirementsSpecification"
$context.source.document.titleSource entity’s document title"System Requirements"
Dynamic constraints with $context are evaluated per-row. Different rows can produce different constraint values depending on their source entity’s properties.

​
Dynamic Value (() => expression)

Dynamic values use JavaScript arrow function syntax and are evaluated in sheet configuration contexts. They receive the context object and offer full JavaScript expressiveness for computing values, filtering data, and rendering content at runtime. Where it is used:
Sheet Configuration PropertyPurpose
sources.query.whereFilter data with dynamic predicates
sources.entityFactorySet initial values for new items
columns.*.formulaCalculate column values from other properties
columns.*.renderCustom HTML rendering for cells
columns.*.displayOverride display value for navigation properties
renderers.*Named renderer definitions
formatters.*.expressionConditional formatting expressions

​
Context Availability Matrix

Not all context properties are available in every expression location. The following matrix shows which properties are accessible where:
Usage Location.user.sources.document.item.value.source.entity
where✅✅✅------------
entityFactory✅✅---------------
formula✅✅---✅✅✅✅
render / renderers---------✅✅------
formatter------✅✅✅------
display---------✅✅✅---
Referencing a context property that is not available in the current location returns undefined. This does not produce an error but may cause unexpected behavior in your expressions. Always consult the matrix above.

​
Document Context

Powersheet automatically provides document context information to queries and expressions. When a sheet is embedded in a Polarion LiveDoc, the context.document properties are populated from the hosting document.

​
Document Scoping in Constraints

The applyCurrentDocumentTo constraint property controls whether queries are automatically filtered to the current document: 
sources:
  - id: requirements
    query:
      from: UserNeed
    constraints:
      applyCurrentDocumentTo: UserNeed
When applyCurrentDocumentTo matches the query’s from entity type, the query engine injects predicates for document.moduleFolder and document.moduleName to restrict results to items within the current document.

​
Document ID in Dynamic Expressions

The document ID is available as context.document.id in dynamic value expressions and as a query parameter for server-side resolution: 
sources:
  - id: scoped-items
    query:
      from: SystemRequirement
      where:
        documentId:
          "==": "() => context.document.id"
For details on document constraint variants, see Document Filtering.

​
Project Scoping

All queries executed through Powersheet are automatically scoped to the current Polarion project. The query engine adds a project.id filter to every Lucene query, ensuring results only include entities from the active project. This scoping is applied transparently and does not require explicit configuration.

​
Security Enforcement

Before any query executes, the query engine verifies that the current user has read permission for the requested entity type. If the entity type’s isReadOnly permission check indicates the user lacks access, the query is rejected before reaching the data layer. Entity-level security is enforced through custom metadata annotations on each entity type in the domain model. See Permissions for details on configuring entity-level access.

​
Dynamic Value Examples

​
Filtering by URL Parameter

URL parameters passed to the Powersheet widget (e.g., ?client=Acme) are accessible through context.parameters: 
sources:
  - id: opportunities
    query:
      from: Opportunity
      where:
        Client:
          "==": "() => context.parameters.client"

​
Filtering by Date

Dynamic date calculations use JavaScript date functions. The resulting value must match the data type format --- for dates, use .toISOString(): 
sources:
  - id: upcoming
    query:
      from: Task
      where:
        DueDate:
          ">": "() => new Date().toISOString()"

​
Combining Multiple Parameters

Template literals combine multiple parameter values into a single filter: 
sources:
  - id: filtered
    query:
      from: Opportunity
      where:
        Client:
          "==": "() => `${context.parameters.client} ${context.parameters.status}`"

​
Setting Initial Values for New Entities

The entityFactory property sets default values when creating new work items. Dynamic expressions allow context-sensitive defaults: 
sources:
  - id: requirements
    entityFactory:
      Client: "() => context.parameters.client"

​
Calculated Column Values

The formula property computes a value from other properties on the current entity: 
columns:
  totalPrice:
    formula: "() => context.item.quantity * context.item.unitPrice"
The formula property writes the calculated value back to the data source. Use render if you only need to change how a value is displayed without modifying the underlying data.

​
Custom Cell Rendering

The render property and named renderers produce custom HTML output: 
renderers:
  linkedItems: "() => context.value.map((item) => `<b>${item.name}</b>`).join(', ')"

​
Display Override for Navigation Properties

The display property overrides what is shown for a linked entity column: 
columns:
  systemRequirement.document:
    display: "() => context.document.title"

​
Conditional Formatting

Formatter expressions use a simplified syntax without the () => prefix. The expression is evaluated as a boolean condition: 
formatters:
  criticalHighlight:
    expression: "context.item.Probability <= 99"
    style: warningStyle
Formatter expressions do not start with () =>. They are evaluated directly as boolean conditions against the context object.

​
Context Expression Examples (Domain Model)

​
Filter by Source Document Component

Restrict linked items to the same document component as the source entity: 
relationships:
  - from: DesignRequirement
    to: SystemRequirement
    back:
      name: designRequirements
      constraints:
        load:
          document:
            component: $context.source.document.component
When viewing a SystemRequirement from the “Braking” component, only DesignRequirement items from “Braking” documents are loaded.

​
Filter by Source Document Identity

Restrict to the exact same document as the source entity: 
constraints:
  load:
    document:
      moduleName: $context.source.document.moduleName
      moduleFolder: $context.source.document.moduleFolder

​
Filter by Source Document Type

Restrict picker results to documents of the same type as the source entity’s document: 
constraints:
  pick:
    document:
      type: $context.source.document.type

​
Enum Resolution Context

When picker fields need to load available enum options, Powersheet automatically discovers enum properties from entity metadata and creates specialized data sources for dropdown rendering. Enum sources are constructed from entity metadata properties including the Polarion prototype, work item type, project scope, and enum identifier. The source ID follows the pattern system.enums.<enumId>. No manual configuration is required --- enum sources are auto-generated when metadata loads.

​
Server-Side Rendering Context

For server-rendered properties (Velocity template fields), a separate rendering context is provided containing the current work item, transaction context, and Polarion persistent object reference. See Context Variables for the complete server rendering context.

​
Quick Reference

GoalNotationExample
Filter relationship by source document$contextcomponent: $context.source.document.component
Filter query by URL parameter() =>"==": "() => context.parameters.client"
Calculate column from other fields() =>formula: "() => context.item.qty * context.item.price"
Render custom HTML in a cell() =>render: "() => '<b>' + context.value + '</b>'"
Set default value for new items() =>entityFactory: { Client: "() => context.parameters.client" }
Conditionally style a cellexpressionexpression: "context.item.Risk > 50"