Create a Computed Property - Nextedy Documentation

Prerequisites

A working data 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:

Approach	Syntax	Runs On	Defined In	Best For
Server-rendered property	`serverRender: "$item.id"`	Server (Velocity)	Data-model YAML	Accessing Polarion services, secure calculations, cross-entity queries
Dynamic value expression	`formula: "() => context.item.qty * context.item.price"`	Client (JavaScript)	Sheet-configuration YAML	UI-driven calculations, formatting, parameter-based filtering

The two mechanisms live in different files. serverRender must be defined in the data model YAML (it needs Polarion platform access); formula / () => expressions must be defined in the sheet configuration YAML (they run client-side and need UI reactivity). Putting either in the wrong file has no effect.

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 Data Model

Open your data 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:

Variable	Type	Description	Availability
`$item`	ModelObject	Work item model object (`.id`, `.title`, `.status`, `.author`, `.created`, `.updated`)	All work items
`$wi`	IWorkItem	Low-level Polarion work item API for operations not available on `$item`	Work item entities only
`$module`	IModule	Current LiveDoc (`.moduleFolder`, `.moduleName`, `.space`)	Document-scoped entities
`$context`	PowersheetContext	Powersheet context (project, document scope, query helpers)	Always
`$tx`	Transaction	Current transaction for read-only operations	Always

In addition, the Polarion platform services ($trackerService, $txService, $repositoryService, $securityService) are automatically injected and cached for performance. For the full list and what each service is for, see Platform Services in the Velocity Templates reference. 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 — count directly linked work items using $wi (the low-level work item API, for methods not available on $item):

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

A property with serverRender is always read-only — even if you set updatable: true, the rendering mechanism overrides it and prevents client-side edits, since the value is always recomputed from the template. Setting updatable: false explicitly just avoids confusing the column display. See Configure Read-Only Column for how this interacts with the other read-only resolution rules.

Step 4: Display the Property in Your Sheet

Add a column in your sheet configuration that binds to the computed property:

columns:
  computedLabel:
    title: "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

customFieldName maps a data-model property to a Polarion custom field by its field ID, so the property reads and writes that custom field’s value. Once mapped, you can reference the property within a 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

serverName aliases a property to a different underlying Polarion field ID: the property keeps its client-facing name in the sheet while reading and writing the field named by serverName on the server. Use it when the Polarion field name differs from the name you want to expose:

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:
    title: "Total Price"
    formula: "() => context.item.quantity * context.item.unitPrice"

Formula writes back to the data source

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. In the table below, ✅ means the property is available at that location and -- means it is not available:

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 current document:

sources:
  - id: opportunities
    query:
      from: Opportunity
      where:
        Module:
          "==": "() => context.document.moduleName"

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 Type	Cause	Fix
`ParseErrorException`	Invalid Velocity syntax	Check template for unclosed directives or typos
`MethodInvocationException`	Called method threw an exception	Verify the method exists on the target object
`ResourceNotFoundException`	Referenced resource not found	Check 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.

Column renders the literal template text, or does not appear at all

A computed column that shows the raw template (e.g. $item.id - $item.title) verbatim instead of the evaluated value — or that does not appear in the sheet at all — usually points to one of the following. Work through them in order:

Install-time cache not cleared. This is the most common cause. The serverRender annotation is only picked up after the install-time caches are cleared and the server is restarted. Confirm that both [POLARION_DATA]/workspace/.config and [POLARION_DATA]/workspace/.metadata were deleted and Polarion was fully restarted — a stale .metadata cache in particular lets the plugin load while server-side rendering silently fails to engage. See Installing Powersheet, Step 1 for the exact procedure.
polarionType mismatch. Confirm the entity’s polarionType matches the real Polarion work-item type ID exactly — the match is case-sensitive. If it does not match a real type, the property is never bound to live work items and nothing is rendered.
Document caches its column layout. An existing Powersheet document caches the columns it was opened with, so a newly added column may not appear until you fully close and re-open (or reload) the document — the in-sheet refresh action alone is not always enough.

These are diagnostic steps for the most frequent causes. If a column still renders its literal template after working through all three, capture the server logs and the exact property and column YAML, then contact Nextedy support.

Dynamic Value Expressions

Client-side expressions fail silently if the context property is not available. Verify:

You are using the () => prefix (not $context, which is for model constraints only)
The context property is available at the location where you are using it (see the availability table above)
Property names match your data model exactly (case-sensitive)

Verification

After saving your YAML configuration and reloading the sheet:

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
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
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.

​Prerequisites

​Choose Your Approach

​Option A: Server-Rendered Property (Velocity)

​Step 1: Add the Property to Your Data Model

​Step 2: Use Context Variables in Your Template

​Step 3: Mark the Property as Read-Only

​Step 4: Display the Property in Your Sheet

​Step 5: Use Custom Field Data in Templates

​Step 6: Alias Field Names with serverName

​Option B: Dynamic Value Expression (JavaScript)

​Step 1: Add a Formula Column

​Step 2: Understand Context Availability

​Step 3: Use Dynamic Expressions in Different Locations

​Step 4: Add Conditional Formatting

​Debugging Computed Properties

​Server-Rendered Properties

​Column renders the literal template text, or does not appear at all

​Dynamic Value Expressions

​Verification

​See Also

Prerequisites

Choose Your Approach

Option A: Server-Rendered Property (Velocity)

Step 1: Add the Property to Your Data Model

Step 2: Use Context Variables in Your Template

Step 3: Mark the Property as Read-Only

Step 4: Display the Property in Your Sheet

Step 5: Use Custom Field Data in Templates

Step 6: Alias Field Names with serverName

Option B: Dynamic Value Expression (JavaScript)

Step 1: Add a Formula Column

Step 2: Understand Context Availability

Step 3: Use Dynamic Expressions in Different Locations

Step 4: Add Conditional Formatting

Debugging Computed Properties

Server-Rendered Properties

Column renders the literal template text, or does not appear at all

Dynamic Value Expressions

Verification

See Also