Expression Notations Overview Powersheet uses two distinct expression notations depending on the configuration file type:
Notation Syntax Configuration File Purpose Context expression $context.property.pathDomain model YAML (constraints) Dot-notation property access, no JavaScript Dynamic value () => expressionSheet configuration YAML (sources, columns, formatters) Full JavaScript arrow function
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 object. They are used exclusively in domain model configuration — specifically in constraint definitions. No JavaScript logic is supported; only direct property path access.
Where $context Is Used Configuration Location Description domainModelTypes.*.constraintsEntity type constraints relationships.*.direct.constraintsDirect relationship constraints relationships.*.back.constraintsBack relationship constraints
Available Context Paths Path Type Description Example Value $context.source.typestringSource entity’s work item type "sys_req"$context.source.document.idstringSource entity’s document ID "Requirements/SRS"$context.source.document.moduleNamestringSource entity’s document module name "UserNeedSpecification"$context.source.document.moduleFolderstringSource entity’s document folder "Requirements"$context.source.document.componentstringSource entity’s document component "Braking"$context.source.document.typestringSource entity’s document type "systemRequirementsSpecification"$context.source.document.titlestringSource 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 ExamplesFilter 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.whereFilter data with dynamic predicates "() => context.parameters.client"sources[].entityFactorySet initial values for new items "() => context.parameters.client"columns.*.formulaCalculate column values from other properties "() => context.item.qty * context.item.price"columns.*.renderCustom HTML rendering for cells "() => '<b>' + context.value + '</b>'"columns.*.displayOverride display value for navigation properties "() => context.document.title"renderers.*Named renderer definitions "() => context.value.map(...)"formatters.*.expressionConditional 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 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 (per-cell contexts only) | +-- {propertyName} e.g. context.item.StoryPoints +-- source Parent/source entity (relationship contexts) | +-- {propertyName} e.g. context.source.document.component +-- 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.usercontext.sourcescontext.documentcontext.itemcontext.valuecontext.sourcecontext.entitywhere (source query)✅ ✅ ✅ — — — — entityFactory✅ ✅ — — — — — formula✅ ✅ — ✅ ✅ ✅ ✅ render / renderers— — — ✅ ✅ — — formatter— — ✅ ✅ ✅ — — display— — — ✅ ✅ ✅ —
Context Properties Reference Property Type Description context.parametersobjectKey-value pairs from URL parameters and widget configuration context.parameters.{name}stringIndividual parameter value, accessed by name context.userobjectCurrent logged-in user information context.user.idstringUser identifier context.user.namestringDisplay name of the current user context.sourcesarrayAll configured data source definitions from the sheet configuration context.documentobjectCurrent document metadata context.document.titlestringDocument title context.document.typestringDocument type identifier context.document.idstringDocument ID context.document.moduleNamestringLiveDoc module name context.document.moduleFolderstringLiveDoc module folder path context.document.componentstringDocument component identifier context.toolobjectCurrent tool information context.tool.typestringTool type identifier context.itemobjectCurrent entity being processed (per-cell only) context.item.{propertyName}anyAny property of the current entity, accessed by name context.sourceobjectParent/source entity in relationship contexts context.entityobjectCurrent entity as a plain data object context.valueanyCurrent cell’s resolved display value
Expression Examples by Use Case Source Query Filtering (where) Filter by a URL parameter: sources : - id : opportunities query : from : Opportunity where : Client : "==" : "() => context.parameters.client"
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.
Combine multiple parameters using template literals: sources : - id : filteredItems query : from : WorkItem where : Client : "==" : "() => `${context.parameters.client} ${context.parameters.status}`"
Entity Factory (Default Values for New Items) Set initial values from URL parameters: sources : - id : opportunities query : from : Opportunity entityFactory : Client : "() => context.parameters.client" AccountId : "0010900000rQli1AAC" StageName : Prospecting
Static values (like AccountId and StageName above) and dynamic expressions can be mixed freely in the same entityFactory block.
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
Column Display (Navigation Property Override) Show the document title instead of the default display value: columns : systemRequirement.document : display : "() => context.document.title"
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()" entityFactory : Project : "() => context.parameters.project" 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 : title : System Requirement width : 200 render : linkedItems systemRequirements.systemRequirement.designRequirements.designRequirement.title : title : Design Requirement width : 200 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.title : visible : false sortBy : - columnId : priority direction : desc - columnId : title direction : asc
Quick Reference I want to… Notation Example Filter relationship by source document $contextcomponent: $context.source.document.componentFilter query by URL parameter () =>"==": "() => context.parameters.client"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 value for new items () =>Client: "() => context.parameters.client"Conditionally style a cell expression expression: "context.item.Risk > 50"Display linked entity property () =>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 : AccountId : "0010900000rQli1AAC" # Static — always this value Client : "() => context.parameters.client" # 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
Using Template Literals for String Interpolation When you need to construct strings from multiple parameters, use JavaScript template literals:
where : FullKey : "==" : "() => `${context.parameters.project}-${context.parameters.id}`"
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.
Nested Navigation in Render Expressions 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/>')"
Related Pages
Binding Syntax — column key path structure and navigation patternsColumns — full column property reference including formula, render, and displayFormatters — conditional formatting configuration and style referencesStyles — style definitions used by formatters and column headersSources — data source configuration including query.where and entityFactoryRender Property — detailed reference for custom renderingDisplay Property — display override for navigation property columnsConstraints — constraint configuration where $context expressions are usedContext Expressions Reference — extended reference on $context paths in domain models
Authoritative references: Dynamic Value Expressions (internal KB), Sheet configuration (internal KB).
