Dynamic Value Expressions Reference

Expression Notations Overview

Powersheet uses two distinct expression notations depending on the configuration file type:

Notation	Syntax	Configuration File	Purpose
Context expression	`$context.property.path`	Data model YAML (constraints)	Dot-notation property access, no JavaScript
Dynamic value	`() => expression`	Sheet configuration YAML (sources, columns, formatters)	Full JavaScript arrow function

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 object. They are used exclusively in data model configuration — specifically in constraint definitions. No JavaScript logic is supported; only direct property path access.

Where `$context` Is Used

Configuration Location	Description
`domainModelTypes.*.constraints`	Entity type constraints
`relationships.*.direct.constraints`	Direct relationship constraints
`relationships.*.back.constraints`	Back relationship constraints

Available Context Paths

Path	Type	Description	Example Value
`$context.source.type`	`string`	Source entity’s work item type	`"sys_req"`
`$context.source.document.id`	`string`	Source entity’s document ID	`"Requirements/SRS"`
`$context.source.document.moduleName`	`string`	Source entity’s document module name	`"UserNeedSpecification"`
`$context.source.document.moduleFolder`	`string`	Source entity’s document folder	`"Requirements"`
`$context.source.document.component`	`string`	Source entity’s document component	`"Braking"`
`$context.source.document.type`	`string`	Source entity’s document type	`"systemRequirementsSpecification"`
`$context.source.document.title`	`string`	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.

`$context` Examples

Filter linked items to the same document component as the source item:

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 linked items to the same document as the source item:

constraints:
  load:
    document:
      moduleName: $context.source.document.moduleName
      moduleFolder: $context.source.document.moduleFolder

Filter by source entity’s document type (pick constraint):

constraints:
  pick:
    document:
      type: $context.source.document.type

Dynamic Value (`() => expression`)

Dynamic values use JavaScript arrow function syntax and are used in sheet configuration YAML. They provide full JavaScript expressiveness for computing values, filtering data, and rendering content at runtime.

How It Works

A () => expression is a JavaScript arrow function that receives a context object. Powersheet evaluates the function at runtime and uses the returned value. The expression must be enclosed in quotes in the YAML configuration.

# General syntax
propertyName: "() => expression using context"

Where `() =>` Is Used

Sheet Configuration Property	Purpose	Example
`sources[].query.where`	Filter data with dynamic predicates	`"() => context.document.moduleName"`
`sources[].entityFactory`	Set initial values for new items	`"() => context.source.type + '_VerificationTestCase'"`
`columns.*.formula`	Calculate column values from other properties	`"() => context.item.qty * context.item.price"`
`columns.*.render`	Custom HTML rendering for cells	`"() => '<b>' + context.value + '</b>'"`
`columns.*.display`	Override display value for navigation properties	`"() => context.item.titleOrName"`
`renderers.*`	Named renderer definitions	`"() => context.value.map(...)"`
`formatters.*.expression`	Conditional formatting expressions	`"context.item.Probability <= 99"`

formula affects persisted data — the calculated value is saved back to the data source. Use render if you only need to change how a value is displayed without modifying the underlying data.

Formatter expressions use a simplified syntax — they do not start with () =>. The expression is evaluated as a boolean condition directly (e.g., "context.item.Risk > 50").

The Context Object

The context object provides runtime information to dynamic expressions. Its structure is hierarchical, and properties are progressively available depending on the evaluation scope.

context
+-- parameters          Configuration parameters (e.g. model ID)
|   +-- model           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 (per-cell contexts only)
|   +-- {propertyName}  e.g. context.item.StoryPoints
+-- source              Parent/source entity (relationship contexts)
|   +-- type, document.*  e.g. context.source.type
+-- entity              Current entity as a plain object
+-- value               Current cell's display value

Context Availability by Location

Not all context properties are available in every expression location. The following table shows which properties are accessible where:

Usage Location	`context.user`	`context.sources`	`context.document`	`context.item`	`context.value`	`context.source`	`context.entity`
`where` (source query)	✅	✅	✅	—	—	—	—
`entityFactory`	✅	✅	—	—	—	✅	—
`formula`	✅	✅	—	✅	✅	✅	✅
`render` / `renderers`	—	—	—	✅	✅	—	—
`formatter`	—	—	✅	✅	✅	—	—
`display`	—	—	—	✅	✅	✅	—

Context Properties Reference

Property	Type	Description
`context.parameters`	`object`	Configuration parameters bag
`context.parameters.model`	`string`	Data model identifier for the active sheet configuration
`context.user`	`object`	Current logged-in user information
`context.user.id`	`string`	User identifier
`context.user.name`	`string`	Display name of the current user
`context.sources`	`array`	All configured data source definitions from the sheet configuration
`context.document`	`object`	Current document metadata
`context.document.title`	`string`	Document title
`context.document.type`	`string`	Document type identifier
`context.document.id`	`string`	Document ID
`context.document.moduleName`	`string`	LiveDoc module name
`context.document.moduleFolder`	`string`	LiveDoc module folder path
`context.document.component`	`string`	Document component identifier
`context.tool`	`object`	Current tool information
`context.tool.type`	`string`	Tool type identifier
`context.item`	`object`	Current entity being processed (per-cell only)
`context.item.{propertyName}`	`any`	Any property of the current entity, accessed by name
`context.source`	`object`	Parent/source entity in relationship contexts
`context.source.type`	`string`	Parent entity’s work item type
`context.entity`	`object`	Current entity as a plain data object
`context.value`	`any`	Current cell’s resolved display value

Expression Examples by Use Case

Source Query Filtering (`where`)

Filter to items in the current document module:

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

This restricts the source query to work items that belong to the same LiveDoc module as the document the sheet is embedded in. Filter by today’s date (future items only):

sources:
  - id: tasks
    query:
      from: Task
      where:
        DueDate:
          ">": "() => new Date().toISOString()"

The resulting value must be in the correct format for the data type. For date fields, always use .toISOString() to produce the expected ISO 8601 string.

Entity Factory (Default Values for New Items)

Derive default values from the parent (source) entity:

sources:
  - id: verificationTestCases
    query:
      from: VerificationTestCase
    entityFactory:
      title: "() => context.source.type + '_VerificationTestCase'"
      status: Draft

In nested or relationship-driven contexts, entityFactory uses context.source to access properties of the parent entity that triggered the row creation. Static values (like status: Draft above) and dynamic expressions can be mixed freely in the same entityFactory block.

Column Formula (Calculated Values)

Calculate a value from other entity properties:

columns:
  totalPrice:
    formula: "() => context.item.quantity * context.item.unitPrice"
    title: Total Price
    isReadOnly: true

Concatenate string properties:

columns:
  fullName:
    formula: "() => `${context.item.firstName} ${context.item.lastName}`"
    title: Full Name
    isReadOnly: true

Column Render (Display-Only HTML)

Bold rendering of a cell value:

columns:
  title:
    render: "() => `<b>${context.value}</b>`"

Named Renderers

Render a collection of linked items as a comma-separated list:

renderers:
  linkedItems: "() => context.value.map((item) => `<b>${item.name}</b>`).join(', ')"

Reference the renderer by name from a column:

columns:
  systemRequirements.systemRequirement.title:
    render: linkedItems

The display property overrides what users see for a navigation column without changing the underlying data binding. It is the most common location for short, focused () => expressions. Show the linked entity’s title or fall back to its name:

columns:
  systemRequirements.systemRequirement:
    display: "() => context.item.titleOrName"

titleOrName is a convenient idiom for entities that may have either a title (work items with rich descriptions) or only a name (lightweight reference entities). Show only the title of the linked entity:

columns:
  systemRequirements.systemRequirement:
    display: "() => context.item.title"

Show the linked entity’s parent document title instead of the entity itself:

columns:
  systemRequirement.document:
    display: "() => context.document.title"

Compose a display string from multiple properties of the linked entity:

columns:
  designRequirements.designRequirement:
    display: "() => `${context.item.id} — ${context.item.title}`"

This pattern is useful when a column shows a single linked item but you want a richer label (for example, an ID prefix followed by a human-readable title).

Conditional Formatting (Formatters)

Highlight rows where probability is below a threshold:

formatters:
  criticalHighlight:
    expression: "context.item.Probability <= 99"
    style: warningStyle

styles:
  warningStyle:
    color: red700
    backgroundColor: red100
    textDecoration: line-through

Formatter expressions do not use the () => prefix. They are evaluated directly as boolean conditions. The formatter references a style definition.

Complete YAML Example

A full sheet configuration demonstrating multiple dynamic expression patterns:

sources:
  - id: userNeeds
    query:
      from: UserNeed
      where:
        Status:
          "!=": "() => 'Rejected'"
        DueDate:
          ">": "() => new Date().toISOString()"
        document.moduleName:
          "==": "() => context.document.moduleName"
    entityFactory:
      Status: Draft
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements

columns:
  id:
    title: ID
    width: 80
    isReadOnly: true
  title:
    title: User Need
    width: 200
    hasFocus: true
  priority:
    title: Priority
    width: 100
    formatter: highPriority
  riskScore:
    title: Risk Score
    width: 120
    formula: "() => context.item.severity * context.item.probability"
    isReadOnly: true
  systemRequirements.systemRequirement:
    title: System Requirement
    width: 220
    display: "() => context.item.titleOrName"
  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: Design Requirement
    width: 220
    display: "() => context.item.title"

renderers:
  linkedItems: "() => context.value.map((item) => `<b>${item.name}</b>`).join(', ')"

formatters:
  highPriority:
    expression: "context.item.priority === 'Critical'"
    style: criticalStyle

styles:
  criticalStyle:
    color: red700
    backgroundColor: red100

views:
  Without Design:
    columns:
      systemRequirements.systemRequirement.designRequirements.designRequirement:
        visible: false

sortBy:
  - columnId: priority
    direction: desc
  - columnId: title
    direction: asc

Quick Reference

I want to…	Notation	Example
Filter relationship by source document	`$context`	`component: $context.source.document.component`
Filter query by current document module	`() =>`	`"==": "() => context.document.moduleName"`
Filter query by current date	`() =>`	`">": "() => new Date().toISOString()"`
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 from parent entity	`() =>`	`title: "() => context.source.type + '_TC'"`
Conditionally style a cell	expression	`expression: "context.item.Risk > 50"`
Display linked entity title-or-name	`() =>`	`display: "() => context.item.titleOrName"`
Display the linked document title	`() =>`	`display: "() => context.document.title"`
Render a collection as HTML	`() =>`	`"() => context.value.map(i => i.name).join(', ')"`

Common Patterns and Edge Cases

Combining Static and Dynamic Values

In entityFactory, static and dynamic values coexist. Only values with the () => prefix are evaluated at runtime:

entityFactory:
  status: Draft                                    # Static — always this value
  title: "() => context.source.type + '_TC'"       # Dynamic — resolved at runtime

Multiple `$context` Constraints

You can combine multiple $context paths in a single constraint block to narrow the filter:

constraints:
  load:
    document:
      moduleName: $context.source.document.moduleName
      moduleFolder: $context.source.document.moduleFolder
      component: $context.source.document.component

A single navigation column can render very differently depending on the display expression. The same binding systemRequirements.systemRequirement can show:

# Variant A: short — falls back to name when title is missing
display: "() => context.item.titleOrName"

# Variant B: explicit — title only (blank if missing)
display: "() => context.item.title"

# Variant C: composed — ID and title together
display: "() => `${context.item.id} — ${context.item.title}`"

Use display whenever you need to change only how a linked entity appears in a cell, without changing the underlying binding path or affecting other views.

Date Handling

Date comparisons require ISO 8601 format. Always call .toISOString() on Date objects:

where:
  CreatedDate:
    ">=": "() => new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString()"

The example above filters for items created within the last 7 days. When rendering values from expanded entities, context.value contains the resolved data. For collections, use .map() and .join():

renderers:
  testResults: "() => context.value.map((tc) => `${tc.name}: ${tc.status}`).join('<br/>')"

Binding Syntax — column key path structure and navigation patterns
Columns — full column property reference including formula, render, and display
Formatters — conditional formatting configuration and style references
Styles — style definitions used by formatters and column headers
Sources — data source configuration including query.where and entityFactory
Render Property — detailed reference for custom rendering
Display Property — display override for navigation property columns
Constraints — constraint configuration where $context expressions are used
Context Expressions Reference — extended reference on $context paths in data models

Expression Notations Overview

Context Expression (`$context`)

Where `$context` Is Used

Available Context Paths

`$context` Examples

Dynamic Value (`() => expression`)

How It Works

Where `() =>` Is Used

The Context Object

Context Availability by Location

Context Properties Reference

Expression Examples by Use Case

Source Query Filtering (`where`)

Entity Factory (Default Values for New Items)

Column Formula (Calculated Values)

Column Render (Display-Only HTML)

Named Renderers

Column Display (Navigation Property Override)

Conditional Formatting (Formatters)

Complete YAML Example

Quick Reference

Common Patterns and Edge Cases

Combining Static and Dynamic Values

Multiple `$context` Constraints

Display Variants for the Same Navigation Column

Date Handling

Nested Navigation in Render Expressions

​Expression Notations Overview

​Context Expression ($context)

​Where $context Is Used

​Available Context Paths

​$context Examples

​Dynamic Value (() => expression)

​How It Works

​Where () => Is Used

​The Context Object

​Context Availability by Location

​Context Properties Reference

​Expression Examples by Use Case

​Source Query Filtering (where)

​Entity Factory (Default Values for New Items)

​Column Formula (Calculated Values)

​Column Render (Display-Only HTML)

​Named Renderers

​Column Display (Navigation Property Override)

​Conditional Formatting (Formatters)

​Complete YAML Example

​Quick Reference

​Common Patterns and Edge Cases

​Combining Static and Dynamic Values

​Multiple $context Constraints

​Display Variants for the Same Navigation Column

​Date Handling

​Nested Navigation in Render Expressions

​Related Pages

Expression Notations Overview

Context Expression (`$context`)

Where `$context` Is Used

Available Context Paths

`$context` Examples

Dynamic Value (`() => expression`)

How It Works

Where `() =>` Is Used

The Context Object

Context Availability by Location

Context Properties Reference

Expression Examples by Use Case

Source Query Filtering (`where`)

Entity Factory (Default Values for New Items)

Column Formula (Calculated Values)

Column Render (Display-Only HTML)

Named Renderers

Column Display (Navigation Property Override)

Conditional Formatting (Formatters)

Complete YAML Example

Quick Reference

Common Patterns and Edge Cases

Combining Static and Dynamic Values

Multiple `$context` Constraints

Display Variants for the Same Navigation Column

Date Handling

Nested Navigation in Render Expressions

Related Pages