> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Velocity Templates

> Nextedy POWERSHEET uses Apache Velocity templates to render dynamic property values on the Siemens Polarion ALM server.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Template Evaluation

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/server-rendering/velocity-templates/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=dc1f83bbaa7e251a594542b3d9563b05" alt="diagram" style={{ width: "520px", maxWidth: "100%" }} width="520" height="180" data-path="powersheet/diagrams/reference/server-rendering/velocity-templates/diagram-1.svg" />
</Frame>

## 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:

```velocity theme={null}
## $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](/powersheet/reference/server-rendering/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                |

<Info title="Verify in application">
  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.
</Info>

## 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](#method-calls) below). See [Polarion Services](/powersheet/reference/server-rendering/polarion-services) for detailed service documentation.

## Template Syntax

Velocity templates use standard Apache Velocity syntax.

### Variable References

```velocity theme={null}
$item.title
$item.status.id
$wi.getLinkedWorkItems()
```

### Conditional Logic

```velocity theme={null}
#if($item.status.id == "approved")
  Approved
#else
  Pending
#end
```

### Method Calls

```velocity theme={null}
$trackerService.getWorkItemByUri($item.uri)
$securityService.getCurrentUser().getId()
```

<Info title="Verify in application">
  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.

  <Note>
    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.
  </Note>
</Info>

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

<Warning title="Error Marker">
  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).
</Warning>

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

<Tip title="Performance Consideration">
  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.
</Tip>

## 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](/powersheet/guides/sheet-configuration/configure-read-only-column#how-read-only-resolution-works).

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

```velocity theme={null}
$context.document.id
```

See [JavaScript Functions](/powersheet/reference/server-rendering/javascript-functions) for client-side `$context` expressions.

## Complete YAML Example

Data model with a server-rendered property:

```yaml theme={null}
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:

```yaml theme={null}
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'"
```

## Related Pages

* [Render Property](/powersheet/reference/sheet-config/render-property) -- sheet-level render configuration
* [Properties](/powersheet/reference/data-model/properties) -- data model property definitions
* [Configure Read-Only Column](/powersheet/guides/sheet-configuration/configure-read-only-column) -- how `serverRender` properties resolve as read-only

(The [Context Variables](/powersheet/reference/server-rendering/context-variables) and [Polarion Services](/powersheet/reference/server-rendering/polarion-services) references are linked inline from the sections above.)

***

<LastReviewed date="2026-07-02" />