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

Rule of ThumbIf 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"`

Per-Row EvaluationDynamic 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.*.value`	Compute a column’s content from other properties	`"() => context.entity.count * context.entity.rate"`
`columns.*.formula`	Deprecated spelling of `columns.*.value` — identical behaviour	`"() => context.entity.qty * context.entity.price"`
`columns.*.render`	Custom HTML rendering for cells	`"() => '<b>' + context.value + '</b>'"`
`columns.*.display`	Override display value for navigation properties	`"() => context.entity.titleOrName"`
`renderers.*`	Named renderer definitions	`"() => context.value.map(...)"`
`formatters.*.expression`	Conditional formatting expressions	`"context.entity.Probability <= 99"`

value is about data; render and display are about appearance.On a column bound to a real property, value affects persisted data — the computed result is saved back to that property. Use render if you only need to change how a value is displayed without modifying the underlying data. If the result should never be stored at all, prefix the binding key with $ to make the column unbound.

formula is deprecated. Use value.Both names mean exactly the same thing, and existing configurations keep working unchanged, but formula is deprecated. Write value in new configurations. Declaring both on one column is rejected. See Computed Columns.

Formatter ExceptionFormatter expressions use a simplified syntax — they do not start with () =>. The expression is evaluated as a boolean condition directly (e.g., "context.entity.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
+-- entity              Current entity (per-cell contexts only)
|   +-- {propertyName}  e.g. context.entity.severity
+-- source              Parent/source entity — the level navigated from
|   +-- type, document.*  e.g. context.source.type
+-- row                 The whole row across every level
|   +-- entities[]      e.g. context.row.entities[0]
+-- value               Current cell's display value
+-- item                Deprecated alias of context.entity

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.entity`	`context.value`	`context.source`	`context.row`	`context.item`
`where` (source query)	✅	✅	✅	—	—	—	—	—
`entityFactory`	✅	✅	—	—	—	✅	—	—
`value` on a bound column	✅	✅	—	✅	—	—	—	✅
`value` on an unbound column	✅	✅	—	✅	—	✅	✅	✅
`render` / `renderers`	—	—	—	✅	✅	—	—	✅
`formatter`	—	—	✅	✅	✅	—	—	✅
`display`	—	—	—	✅	✅	✅	—	✅

context.item is deprecated because it’s ambiguous — in some cell expressions it’s the entity, in others the whole row. Use context.entity or context.row instead; each always means exactly one thing.

A computed column starts from no cell value.context.value is undefined inside a value expression, whether the column is bound or unbound, because the cell has nothing stored yet. Read what you need from context.entity instead.Only an unbound column’s value expression receives context.row and context.source. A bound value column is evaluated as a calculated property of the entity alone, with no row behind it.

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.entity`	`object`	Current entity being processed (per-cell only). For a column with a navigation binding path, this is the entity the path resolves to
`context.entity.{propertyName}`	`any`	Any property of the current entity, accessed by name
`context.source`	`object`	Parent/source entity — the level the current one was navigated from
`context.source.type`	`string`	Parent entity’s work item type
`context.row`	`object`	The whole row the cell belongs to
`context.row.entities`	`array`	One entry per navigation level, indexed from the root; an entry is `undefined` where the row has no entity at that level
`context.value`	`any`	Current cell’s resolved display value. A JSON object or array is decoded; any other string is passed through unchanged
`context.item`	`object`	Deprecated. Alias of `context.entity` in cell expressions. Kept so existing configurations keep working

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

Date FormattingThe 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 Value (Computed Columns)

Compute a value from other entity properties and store it in the bound property:

columns:
  total:
    value: "() => context.entity.count * context.entity.rate"
    title: Total Price

A computed column is read-only by definition — its content comes from the expression, so there is no need to declare isReadOnly. Concatenate string properties:

columns:
  fullName:
    value: "() => `${context.entity.firstName} ${context.entity.lastName}`"
    title: Full Name

Compute a value that is displayed but never stored: Prefix the binding key with $ to make the column unbound. It has no property behind it, so declare the result type with valueType:

columns:
  $riskScore:
    title: Risk Score
    value: "() => context.entity.Probability * context.entity.Severity"
    valueType: number

Reach the level above, or the whole row, from an unbound column:

columns:
  systemRequirements.systemRequirement.$origin:
    title: Origin
    value: "() => `${context.source.id} → ${context.entity.id}`"

See Add a Computed Column for the full walkthrough and Computed Columns for the property reference.

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.entity.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.entity.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.entity.id} — ${context.entity.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.entity.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
    value: "() => context.entity.severity * context.entity.probability"
  $riskBand:
    title: Risk Band
    width: 100
    value: "() => context.entity.severity * context.entity.probability > 50 ? 'High' : 'Low'"
    valueType: string
  systemRequirements.systemRequirement:
    title: System Requirement
    width: 220
    display: "() => context.entity.titleOrName"
  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: Design Requirement
    width: 220
    display: "() => context.entity.title"

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

formatters:
  highPriority:
    expression: "context.entity.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()"`
Compute a column and store the result	`() =>`	`value: "() => context.entity.count * context.entity.rate"`
Compute a column without storing anything	`() =>`	`$total:` with `value: "() => …"` and `valueType: number`
Read the level above from a computed column	`() =>`	`value: "() => context.source.id"`
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.entity.Risk > 50"`
Display linked entity title-or-name	`() =>`	`display: "() => context.entity.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.entity.titleOrName"

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

# Variant C: composed — ID and title together
display: "() => `${context.entity.id} — ${context.entity.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, navigation patterns, and the $ unbound marker
Columns — full column property reference including value, valueType, render, and display
Add a Computed Column — step-by-step guide to stored and display-only computed columns
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 Value (Computed Columns)

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 Value (Computed Columns)

​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 Value (Computed Columns)

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