Velocity Templates - Nextedy Documentation

Template Evaluation

Context Variables

The following variables are available in every Velocity template evaluation.

Variable	Type	Description
`$item`	ModelObject	Primary work item accessor. Provides access to all work item properties and methods.
`$wi`	IWorkItem	Legacy Polarion work item API. Only available for work item entities. Use for methods not available on `$item`.
`$tx`	Transaction	Current transaction object for transactional queries and read-only operations.
`$module`	IModule	Document (LiveDoc) containing the work item. `null` for entities not within a document.
`$context`	PowersheetContext	Powersheet-specific context providing access to project scope, document scope, and query capabilities.
`$pObject`	IPObject	Raw Polarion persistent object underlying the entity (`.uri`, `.contextId`).

Examples

$item (ModelObject) exposes work item fields directly; $wi (IWorkItem) is the low-level Polarion API for operations not surfaced on $item, such as link traversal:

## $item -- high-level field access
$item.id - $item.title ($item.status.id)

## $wi -- low-level API for methods not on $item
#set($links = $wi.getLinkedWorkItems())
$links.size() linked items

See Context Variables for detailed documentation on each variable, including the full $item, $wi, and $pObject member lists.

`$context` members

The $context (PowersheetContext) variable groups the Powersheet-specific scope and query helpers. Access members by name, for example $context.document.id:

Member	Description
`$context.document`	Current document scope — `.id` returns the document path (`folder/name`)
`$context.project`	Current project information (e.g. `.id`)
Query helpers	Utilities for executing scoped queries within the template

The exact members available on $context depend on the Powersheet version. Consult the Polarion server logs for the available context properties if a member does not resolve.

Platform Services

Platform services are cached and pre-injected into every template evaluation.

Variable	Service	Purpose
`$trackerService`	ITrackerService	Query work items, access project metadata, run Lucene searches
`$txService`	ITransactionService	Transaction management within templates
`$repositoryService`	IRepositoryService	Access project metadata, users, roles, repository configuration
`$securityService`	ISecurityService	Check permissions, implement role-based visibility

The method examples shown for these services throughout this page are illustrative — the exact method set on each service depends on your Polarion server version (see Verify in application below). See Polarion Services for detailed service documentation.

Template Syntax

Velocity templates use standard Apache Velocity syntax.

Variable References

$item.title
$item.status.id
$wi.getLinkedWorkItems()

Conditional Logic

#if($item.status.id == "approved")
  Approved
#else
  Pending
#end

Method Calls

$trackerService.getWorkItemByUri($item.uri)
$securityService.getCurrentUser().getId()

The exact methods available on each service depend on the Polarion server version. The authoritative, version-matched reference is the Polarion SDK Javadoc, which ships with your installation — open [POLARION_INSTALL]/polarion/SDK/doc/sdk/index.html (the interfaces above, such as ITrackerService and ISecurityService, are documented there). Always confirm method signatures against the SDK for your server version rather than relying on the illustrative examples here.

A stable public URL for the Polarion Javadoc is intentionally not linked here, because Siemens does not publish a version-agnostic permalink and the API surface differs between releases. Use the locally shipped SDK Javadoc above, or the official Siemens Polarion developer documentation for your specific version.

Error Handling

Error Type	Behavior
Parse error	Returns `#SERVER_RENDER_ERROR` constant
Method invocation error	Returns `#SERVER_RENDER_ERROR` constant
Resource not found	Returns `#SERVER_RENDER_ERROR` constant

When a Velocity template fails to evaluate, the cell displays #SERVER_RENDER_ERROR. Check the Polarion server logs for the specific error details (parse errors, method invocation errors, or missing resources).

Template Performance

Aspect	Detail
Service context caching	Platform services (`$trackerService`, etc.) are cached in a static context and reused across all template evaluations
Per-item context	`$item`, `$wi`, `$module`, and `$context` are set per work item evaluation
Evaluation scope	Templates execute once per work item per query

Server-rendered templates execute for every work item returned by a query. Avoid expensive operations (e.g., complex Lucene queries within templates) that multiply across large result sets.

Server-Rendered Property Configuration

Server-rendered properties are defined in the data model using the serverRender annotation. When a property has serverRender configured, it becomes read-only (not updatable) regardless of other permission settings. This is part of the broader read-only resolution behavior documented canonically in Configure Read-Only Column.

Property	Type	Default	Description
`serverRender`	`string`	`null`	Velocity template pattern to evaluate. When set, property is automatically marked read-only.
`readable`	`boolean`	`true`	Whether the property is visible to clients
`updatable`	`boolean`	`true`, but forced to `false` when `serverRender` is set	The general default for `updatable` is `true`; for a server-rendered property Powersheet overrides the effective value to `false` and ignores any `updatable: true` you set

Test Context Validation

The server renderer validates that the Velocity context contains the required variables:

Required Variable	Type
`item`	ModelObject (work item)
`tx`	Transaction
`context`	PowersheetContext
`pObject`	IPObject (raw Polarion object)

Document Parameters in Templates

Document parameters can be used within Velocity templates via the $context variable:

$context.document.id

See JavaScript Functions for client-side $context expressions.

Complete YAML Example

Data model with a server-rendered property:

domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    properties:
      title:
      severity:
      computedStatus:
        serverRender: |
          #if($item.status.id == "approved")Approved#else$item.status.id#end

Sheet configuration referencing the computed property:

columns:
  id:
    width: 80
  title:
    width: 300
    hasFocus: true
  computedStatus:
    width: 120
    formatter: readOnly

sources:
  - id: requirements
    title: System Requirements
    model: rtm
    query:
      from: SystemRequirement
      where: "type = 'UserNeed'"

Render Property — sheet-level render configuration
Properties — data model property definitions
Configure Read-Only Column — how serverRender properties resolve as read-only

(The Context Variables and Polarion Services references are linked inline from the sections above.)

​Template Evaluation

​Context Variables

​Examples

​$context members

​Platform Services

​Template Syntax

​Variable References

​Conditional Logic

​Method Calls

​Error Handling

​Template Performance

​Server-Rendered Property Configuration

​Test Context Validation

​Document Parameters in Templates

​Complete YAML Example

​Related Pages

Template Evaluation

Context Variables

Examples

`$context` members

Platform Services

Template Syntax

Variable References

Conditional Logic

Method Calls

Error Handling

Template Performance

Server-Rendered Property Configuration

Test Context Validation

Document Parameters in Templates

Complete YAML Example

Related Pages