Skip to main content

​
Prerequisites

  • A working domain model with at least one entity type
  • A sheet configuration displaying entity properties
  • Access to the project SVN repository to edit YAML configuration files

​
Choose Your Approach

Powersheet supports two mechanisms for computed properties, each suited to different use cases:
ApproachSyntaxRuns OnBest For
Server-rendered propertyserverRender: "$item.id"Server (Velocity)Accessing Polarion services, secure calculations, cross-entity queries
Dynamic value expressionformula: "() => context.item.qty * context.item.price"Client (JavaScript)UI-driven calculations, formatting, parameter-based filtering
Use serverRender in domain model YAML when you need Polarion platform access. Use () => expressions in sheet configuration YAML when you need client-side reactivity.
diagram

​
Option A: Server-Rendered Property (Velocity)

Use this approach when you need to compute a value on the server using Polarion platform services and work item data.

​
Step 1: Add the Property to Your Domain Model

Open your domain model YAML file and add a property with a serverRender pattern to the target entity type. The value is a Velocity template expression that the server evaluates for each work item: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    properties:
      title:
        type: string
      computedLabel:
        serverRender: "$item.id - $item.title"
The serverRender value is a standard Velocity template string. The server evaluates it in a context that includes the current work item and Polarion platform services.

​
Step 2: Use Context Variables in Your Template

Server-rendered properties have access to these context variables during evaluation:
VariableTypeDescriptionAvailability
$itemModelObjectWork item model object (.id, .title, .status, .author, .created, .updated)All work items
$wiIWorkItemLow-level Polarion work item API for operations not available on $itemWork item entities only
$moduleIModuleCurrent LiveDoc (.moduleFolder, .moduleName, .space)Document-scoped entities
$contextIDatabridgeContextPowersheet context (project, document scope, query helpers)Always
$txTransactionCurrent transaction for read-only operationsAlways
In addition, the following Polarion platform services are automatically injected and cached for performance:
Service VariablePurpose
$trackerServiceQuery work items, access project metadata, run Lucene queries
$txServiceTransaction management and execution context
$repositoryServiceAccess project metadata, users, roles, and repository configuration
$securityServiceCheck user permissions, implement role-based visibility
Example — concatenate ID and title with a status badge: 
properties:
  statusLabel:
    serverRender: "$item.id [$item.status.id] $item.title"
Example — conditional label using Velocity directives: 
properties:
  riskLabel:
    serverRender: "#if($item.riskScore > 5)High Risk#{else}Low Risk#end"
    readable: true
    updatable: false
Velocity templates support #if, #else, #foreach, #set, and other directives. Use them to create dynamic labels, computed statuses, or aggregated displays.
Example — query related work items using $trackerService: 
properties:
  linkedCount:
    serverRender: "#set($links = $wi.getLinkedWorkItemsStructsDirect())$links.size()"

​
Step 3: Mark the Property as Read-Only

Server-rendered properties are automatically treated as non-editable by the rendering mechanism. You should explicitly set readable: true and updatable: false in your property definition to make the intent clear: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    properties:
      computedLabel:
        serverRender: "$item.id - $item.title"
        readable: true
        updatable: false
Even if you set updatable: true, the server rendering mechanism overrides this setting and prevents client-side edits. The value is always computed from the template. Always set updatable: false to avoid confusing the column display.

​
Step 4: Display the Property in Your Sheet

Add a column in your sheet configuration that binds to the computed property: 
columns:
  computedLabel:
    header: "Requirement Label"
    width: 250
The column displays the server-computed value. Since the property is server-rendered, the value is recalculated on each data load and reflects the latest work item state.

​
Step 5: Use Custom Field Data in Templates

If your entity type maps to a Polarion custom field via customFieldName, you can reference that property within the Velocity template: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    properties:
      riskScore:
        customFieldName: risk_score
      riskSummary:
        serverRender: "#if($item.riskScore > 5)HIGH: Score $item.riskScore#{else}OK#end"
        readable: true
        updatable: false

​
Step 6: Alias Field Names with serverName

When the Polarion field name differs from the client-facing property name, use serverName to create an alias: 
properties:
  friendlyName:
    serverName: internalPolarionFieldId
    type: string
This lets you expose a user-friendly name in the sheet while mapping to the actual Polarion field behind the scenes.

​
Option B: Dynamic Value Expression (JavaScript)

Use this approach for client-side calculations in your sheet configuration. Dynamic value expressions use JavaScript arrow function syntax and are evaluated in the browser.

​
Step 1: Add a Formula Column

To compute a value from other properties on the current item, use the formula property in your column definition: 
columns:
  totalPrice:
    header: "Total Price"
    formula: "() => context.item.quantity * context.item.unitPrice"
The formula property calculates a value and saves it back to the underlying field. If you only need to change how a value is displayed without modifying data, use render instead.

​
Step 2: Understand Context Availability

Not all context properties are available in every location. The available properties depend on where the expression is used:
Usage Location.user.sources.document.item.value.source.entity
where✅✅✅————
entityFactory✅✅—————
formula✅✅—✅✅✅✅
render / renderers———✅✅——
formatter——✅✅✅——
display———✅✅✅—

​
Step 3: Use Dynamic Expressions in Different Locations

Filter a query by URL parameter: 
sources:
  - id: opportunities
    query:
      from: Opportunity
      where:
        Client:
          "==": "() => context.parameters.client"
Render custom HTML in a cell: 
renderers:
  linkedItems: "() => context.value.map((item) => `<b>${item.name}</b>`).join(', ')"
Display a property from a linked entity: 
columns:
  systemRequirement.document:
    display: "() => context.document.title"
Set initial values for new items from a URL parameter: 
entityFactory:
  Client: "() => context.parameters.client"
When using dates in dynamic expressions, always convert to ISO string format: "() => new Date().toISOString()". The resulting value must match the expected data type format.

​
Step 4: Add Conditional Formatting

Formatter expressions use a simplified syntax without the () => prefix. The expression is evaluated as a boolean condition directly: 
formatters:
  criticalHighlight:
    expression: "context.item.Probability <= 99"
    style: warningStyle
Unlike other dynamic expressions, formatter expression values do not use the () => prefix. They are evaluated as direct boolean conditions.

​
Debugging Computed Properties

​
Server-Rendered Properties

If a server-rendered property returns #SERVER_RENDER_ERROR, the Velocity template failed to evaluate. Common causes:
Error TypeCauseFix
ParseErrorExceptionInvalid Velocity syntaxCheck template for unclosed directives or typos
MethodInvocationExceptionCalled method threw an exceptionVerify the method exists on the target object
ResourceNotFoundExceptionReferenced resource not foundCheck that $item, $module, or $wi is available for your entity type
The #SERVER_RENDER_ERROR marker in the cell means the template failed. Check the Polarion server logs for the full stack trace, which includes the specific exception type and the failing template expression.

​
Dynamic Value Expressions

Client-side expressions fail silently if the context property is not available. Verify:
  1. You are using the () => prefix (not $context, which is for model constraints only)
  2. The context property is available at the location where you are using it (see the availability table above)
  3. Property names match your domain model exactly (case-sensitive)

​
Verification

After saving your YAML configuration and reloading the sheet:
  1. Server-rendered property: You should now see the computed value in the column. Edit the underlying work item fields and reload — the computed value updates to reflect the changes
  2. Dynamic formula: You should now see the calculated value appear. If using formula, verify the value is persisted by checking the work item in Polarion
  3. Render/display: You should now see formatted output in the cell without any data modification
If you see #SERVER_RENDER_ERROR in a column, refer to Debug Template Errors for troubleshooting steps.

​
See Also

Source Code
  • ServerRenderer.java
  • Property.java
  • DataPropertyFactory.java
  • MetadataTest.java
  • ServerRendererTest.java
  • QueryDataTest.java
Internal Reference
  • Dynamic Value Expressions (Confluence)