Skip to main content

​
Prerequisites

​
Understand the Two Expression Notations

Powersheet supports two distinct expression syntaxes, each used in a different configuration context:
NotationSyntaxUsed In
Context expression$context.property.pathDomain model configuration (constraints)
Dynamic value() => expressionSheet configuration (where, formula, render, etc.)
If you are editing a domain model YAML file (entity types, relationships), use $context. If you are editing a sheet configuration YAML file (sources, columns, formatters), use () =>.
diagram

​
Step 1: Add a Dynamic Where Clause to a Source Query

Dynamic where clauses let you filter source data using runtime values such as URL parameters or the current date. Filter by a URL parameter: 
sources:
  - id: opportunities
    query:
      from: Opportunity
      where:
        Client:
          "==": "() => context.parameters.client"
When the sheet loads with ?client=Acme in the URL, only records where Client equals Acme are returned. Filter by today’s date (show only future items): 
sources:
  - id: tasks
    query:
      from: Task
      where:
        DueDate:
          ">": "() => new Date().toISOString()"
Dynamic date values must return ISO 8601 format. Always call .toISOString() on Date objects. Returning a raw Date object will cause the query to fail silently.
Combine multiple parameters using template literals: 
sources:
  - id: filtered
    query:
      from: EntityType
      where:
        Client:
          "==": "() => `${context.parameters.client} ${context.parameters.status}`"

​
Step 2: Set Dynamic Default Values with Entity Factory

Use entityFactory to pre-populate fields on newly created items with values resolved at runtime: 
sources:
  - id: userNeeds
    query:
      from: UserNeed
    entityFactory:
      Client: "() => context.parameters.client"
      Status: Planned
In this example, Client receives the URL parameter value at runtime, while Status receives the static value Planned.

​
Step 3: Add a Calculated Column with Formula

The formula property computes a value from other properties on the current entity. The computed value is persisted back to the data source on save. 
columns:
  totalPrice:
    formula: "() => context.item.quantity * context.item.unitPrice"
    title: Total Price
    isReadOnly: true
    format: "c0$"
The expression accesses entity properties through context.item. In this case it multiplies quantity by unitPrice each time the sheet refreshes.
formula modifies the underlying data — the calculated value is saved. If you only need to change how a value is displayed without modifying stored data, use render instead.

​
Step 4: Add a Custom Renderer

Renderers produce custom HTML output for cell display. They do not affect persisted data. Inline render expression on a column: 
columns:
  Priority:
    render: "() => '<b>' + context.value + '</b>'"
    title: Priority
Named renderer definition (reusable across columns): 
renderers:
  linkedItems: "() => context.value.map((item) => `<b>${item.name}</b>`).join(', ')"

columns:
  relatedItems:
    render: linkedItems
    title: Related Items
Named renderers are defined in the top-level renderers section and referenced by name in the column render property.

​
Step 5: Configure Conditional Formatting

Formatters apply styles to cells based on a boolean expression. Unlike formula and render, formatter expressions use simplified syntax — they do not start with () =>. 
formatters:
  criticalHighlight:
    expression: "context.item.Probability <= 99"
    style: warningStyle

styles:
  warningStyle:
    color: red700
    backgroundColor: red100
    textDecoration: line-through
Apply the formatter to a column: 
columns:
  Probability:
    title: Probability
    formatter: criticalHighlight
The formatter context provides access to context.document, context.item, and context.value.

​
Step 6: Use Context Expressions in Domain Model Constraints

In domain model YAML files, use the $context notation to create dynamic constraints that filter relationship data based on the source entity’s properties. Filter linked items to the same document component: 
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 document name and folder: 
constraints:
  load:
    document:
      moduleName: $context.source.document.moduleName
      moduleFolder: $context.source.document.moduleFolder
Constrain picker to same document type: 
constraints:
  pick:
    document:
      type: $context.source.document.type
$context constraints are evaluated per row. Different rows can produce different constraint values depending on their source entity’s properties. This enables context-sensitive filtering without separate configurations.

​
Context Object Reference

The context object provides different properties depending on where the expression is evaluated:
Usage Location.user.sources.document.item.value.source.entity
where✅✅✅————
entityFactory✅✅—————
formula✅✅—✅✅✅✅
render / renderers———✅✅——
formatter——✅✅✅——
display———✅✅✅—
Key context properties:
  • context.parameters — URL and configuration parameters (key-value pairs), e.g., context.parameters.client
  • context.user — Current logged-in user (id, name)
  • context.document — Current document information (title, type, id, moduleName, moduleFolder, component)
  • context.item — Current entity with all its properties, e.g., context.item.StoryPoints
  • context.source — Parent/source entity in relationship contexts
  • context.value — Current cell’s display value

​
Verification

After saving your configuration changes:
  1. Reload the sheet in Polarion
  2. For where clauses: verify that only matching records appear (try different URL parameter values)
  3. For formulas: confirm the calculated column shows correct values and updates when source fields change
  4. For renderers: inspect cells for the expected HTML rendering
  5. For formatters: verify that styling applies when the condition is met and disappears when it is not
  6. For $context constraints: expand a relationship and confirm that only items matching the source entity’s document properties are loaded
You should now see dynamic values resolving correctly at runtime across all configured expression locations.

​
See Also