Query Context - Nextedy Documentation

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          Configuration-supplied parameters
|   +-- model           Dynamic data model ID (e.g. context.parameters.model)
+-- 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)
|   +-- type, {propertyName}  e.g. context.source.type, context.source.document.component
+-- entity              Current entity as a plain object
+-- value               Current cell's display value

Context Properties Reference

Property	Type	Description
`context.parameters`	`object`	Configuration-injected parameters surfaced to the runtime
`context.parameters.model`	`string`	Dynamic data model identifier used to select an RTM model at runtime
`context.user`	`object`	Current authenticated Polarion user
`context.user.id`	`string`	Polarion user ID
`context.user.name`	`string`	Display name of the current user
`context.sources`	`object`	All configured data source definitions from the sheet configuration
`context.document`	`object`	Current Polarion LiveDoc document metadata
`context.document.title`	`string`	Document title
`context.document.type`	`string`	Document type identifier
`context.document.id`	`string`	Full document path in `folder/name` format
`context.document.moduleName`	`string`	Document module name
`context.document.moduleFolder`	`string`	Document folder path
`context.document.component`	`string`	Document component (e.g., `"Braking"`)
`context.tool`	`object`	Current tool information
`context.tool.type`	`string`	Tool type identifier
`context.item`	`object`	Current row entity with all properties accessible by name
`context.item.{propertyName}`	`varies`	Any property of the current entity (e.g., `context.item.StoryPoints`, `context.item.Probability`)
`context.source`	`object`	Parent/source entity in relationship navigation contexts
`context.source.type`	`string`	Parent entity’s work item type (e.g., `"systemRequirement"`)
`context.entity`	`object`	Current entity as a plain JavaScript object
`context.value`	`varies`	Current cell’s resolved display value

Two Expression Notations

Powersheet uses two distinct notations for dynamic expressions, each tied to a specific configuration context.

Notation	Syntax	Used In
Context expression	`$context.property.path`	Data model configuration (constraints)
Dynamic value	`() => expression`	Sheet configuration (`where`, `formula`, `render`, `formatter`, `display`)

If you are editing a data 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 data 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:

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"`

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 Property	Purpose
`sources.query.where`	Filter data with dynamic predicates
`sources.entityFactory`	Set initial values for new items
`columns.*.formula`	Calculate column values from other properties
`columns.*.render`	Custom HTML rendering for cells
`columns.*.display`	Override display value for navigation properties
`renderers.*`	Named renderer definitions
`formatters.*.expression`	Conditional formatting expressions

Context Availability Reference

Not all context properties are available in every expression location. The following reference 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 table 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. The two most commonly used properties in dynamic where clauses are context.document.moduleName and context.document.moduleFolder, which identify the hosting document by name and folder path.

Document Scoping in Constraints

The applyCurrentDocumentTo constraint property controls whether queries are automatically filtered to the current document:

sources:
  - id: requirements
    model: rtm
    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.

Dynamic Value Examples

Filtering by Current Document (Module Name)

The most common dynamic where clause restricts a query to items in the hosting LiveDoc. Use context.document.moduleName to match the document by name:

sources:
  - id: in-document
    query:
      from: SystemRequirement
      where:
        moduleName:
          "==": "() => context.document.moduleName"

For a more precise match that also pins the folder path, combine moduleName with moduleFolder:

where:
  moduleName:
    "==": "() => context.document.moduleName"
  moduleFolder:
    "==": "() => context.document.moduleFolder"

Using `column.display` for Document and Chapter References

The column.display option is the standard way to control how a navigation property is rendered in a cell. For document references, display: titleOrName renders the document’s title when available and falls back to the module name:

columns:
  systemRequirement.document:
    display: titleOrName

For chapter references, display: title renders the chapter heading text:

columns:
  systemRequirement.chapter:
    display: title

These named display modes are preferred over dynamic expressions whenever a column simply needs a standard label for a linked entity.

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()"

Setting Initial Values for New Entities

The entityFactory property sets default values when creating new work items. The factory re-evaluates dynamically based on the parent entity, so context-sensitive defaults are typically derived from context.source:

sources:
  - id: verification
    entityFactory:
      title: '() => context.source.type + "_VerificationTestCase"'

Here, the new test case title is composed from the parent entity’s work item type, so creating a verification case under different sources produces different default titles.

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(', ')"

When the standard display: titleOrName / display: title shorthands are not sufficient, the display property accepts a dynamic expression that 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 (Data 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

Quick Reference

Goal	Notation	Example
Filter relationship by source document	`$context`	`component: $context.source.document.component`
Filter query by current document	`() =>`	`"==": "() => context.document.moduleName"`
Calculate column from other fields	`() =>`	`formula: "() => context.item.qty * context.item.price"`
Render custom HTML in a cell	`() =>`	`render: "() => '<b>' + context.value + '</b>'"`
Display label for a linked entity	shorthand	`display: titleOrName`
Set default value for new items	`() =>`	`entityFactory: { title: "() => context.source.type + '_VTC'" }`
Conditionally style a cell	expression	`expression: "context.item.Risk > 50"`

EntityQuery --- query construction and execution
Predicates --- filtering operators for where clauses
Expand Clause --- loading related entities in queries
Document Filtering --- document-scoping mechanisms
Baseline and Revision Queries --- querying historical data
Dynamic Value Expressions Reference --- complete dynamic expression syntax
Context Expressions Reference --- $context path reference for data models
Constraints --- constraint configuration including stages and operators
Columns --- column-level configuration for formula, render, and display
Formatters --- conditional formatting with expression syntax

​Context Object Structure

​Context Properties Reference

​Two Expression Notations

​Context Expression ($context)

​Dynamic Value (() => expression)

​Context Availability Reference

​Document Context

​Document Scoping in Constraints

​Document ID in Dynamic Expressions

​Project Scoping

​Dynamic Value Examples

​Filtering by Current Document (Module Name)

​Using column.display for Document and Chapter References

​Filtering by Date

​Setting Initial Values for New Entities

​Calculated Column Values

​Custom Cell Rendering

​Display Override for Navigation Properties

​Conditional Formatting

​Context Expression Examples (Data Model)

​Filter by Source Document Component

​Filter by Source Document Identity

​Filter by Source Document Type

​Quick Reference

​Related Pages

Context Object Structure

Context Properties Reference

Two Expression Notations

Context Expression (`$context`)

Dynamic Value (`() => expression`)

Context Availability Reference

Document Context

Document Scoping in Constraints

Document ID in Dynamic Expressions

Project Scoping

Dynamic Value Examples

Filtering by Current Document (Module Name)

Using `column.display` for Document and Chapter References

Filtering by Date

Setting Initial Values for New Entities

Calculated Column Values

Custom Cell Rendering

Display Override for Navigation Properties

Conditional Formatting

Context Expression Examples (Data Model)

Filter by Source Document Component

Filter by Source Document Identity

Filter by Source Document Type

Quick Reference

Related Pages