Velocity Templates - Nextedy Documentation

Template Files

File	Purpose	Endpoint	Required
`risksheetTopPanel.vm`	Renders customizable HTML panel above the Risksheet grid	`/api/panel`	No
`risksheetPdfExport.vm`	Generates JavaScript export script for PDF generation	`/api/pdfscript`	No
sheet configuration	Primary sheet configuration (supports Velocity expressions in values)	`/api/config`	Yes

Template Resolution Properties

Templates are loaded from document attachments with fallback to the template hierarchy. The resolution mechanism tracks where the configuration was found using these properties:

Property	Type	Default	Description
`config`	`string`	File name (e.g., sheet configuration)	Name of the sheet configuration attachment to load from the Polarion document. If not found on the document, the system searches the document’s template hierarchy.
`fromTemplate`	`boolean`	`false`	Flag indicating whether the configuration was loaded from a template document rather than the target document itself. Set to `true` when configuration is inherited from a template module.
`configPath`	`string`	None	URI path to the configuration attachment that was actually loaded, whether from the document itself or from a template. Used for debugging and configuration source tracking.
`templateName`	`string`	None	Display name of the template document from which configuration was inherited. Includes project name prefix if template is from a different project. Empty if configuration is directly attached to the document.
`fileName`	`string`	None	Path and name of the document where configuration was requested (not necessarily where it was found). Formatted as `folder/documentTitle`.
`revision`	`string`	None	Data revision identifier of the cached configuration attachment. Used to invalidate cache when attachment content changes.

Define templates once at the template document level. All documents created from that template inherit the Velocity templates automatically. Override individual templates by attaching a file with the same name directly to a specific document.

Velocity Context Variables

All Risksheet Velocity templates receive a context containing Polarion services, document objects, and utility tools. The available context variables depend on the template type.

Common Context (All Templates)

Variable	Type	Description
`$document` / `$doc`	Polarion Module object	Current Polarion document (module) with access to metadata, custom fields, and work items
`$repositoryService`	Polarion service	Access to Polarion repository operations for querying projects, documents, and work items
`$transaction`	Polarion transaction	Current database transaction for read/write operations within the template
Velocity Tools	Utility objects	Standard Velocity utility tools for formatting, math, and string operations

Top Panel Template Context (`risksheetTopPanel.vm`)

The top panel template renders at the /api/panel endpoint and has full access to the common Velocity context plus:

Additional Context	Description
Document custom fields	Access via `$doc.getOldApi().getValue("fieldId")`
Project configuration	Available through `$repositoryService`
Polarion tracker services	Query work items and links from within the template

Errors in the top panel template render as a red error message box in place of the panel content, displaying the exception details.

PDF Export Template Context (`risksheetPdfExport.vm`)

The PDF export template renders at the /api/pdfscript endpoint and includes additional context:

Additional Context	Type	Description
`pdfExportMacros.vm`	Velocity macros	Helper macros for PDF-specific formatting and layout operations
`revision` parameter	`string`	Required document revision identifier for the export. Must be specified in the request.

See PDF Export Template for detailed template structure and macro reference.

Velocity Syntax Reference

Variables and Properties

## Access a simple variable
$variableName

## Access a nested property
$document.customFields.productFamily

## Access via method call (required for some Polarion APIs)
$doc.getOldApi().getValue("customFieldID")

## Quiet reference (no output if variable is null)
$!{variableName}

Directives

## Set a variable
#set($myVar = "value")

## Conditional rendering
#if($condition)
  content when true
#elseif($otherCondition)
  alternative content
#else
  default content
#end

## Iteration over a collection
#foreach($item in $collection)
  $item.name ($velocityCount of $collection.size())
#end

## Include another template
#parse("included-template.vm")

Embedding JavaScript in Velocity

A key pattern in Risksheet templates is bridging server-side Polarion data to client-side JavaScript logic. The Velocity template executes on the server and generates HTML/JavaScript that runs in the browser:

## Extract document-level custom field on the server
#set($productFamily = $doc.getOldApi().getValue("productFamily"))
#set($projectId = $document.projectId)

<script>
  // Server-rendered values become client-side JavaScript variables
  var productFamily = "$productFamily";
  var projectId = "$projectId";

  // Register a queryFactory in the named map. The engine looks factories
  // up by name; a column references one via typeProperties.queryFactory.
  window.risksheet = window.risksheet || {};
  window.risksheet.queryFactories = window.risksheet.queryFactories || {};
  window.risksheet.queryFactories["filterByProductFamily"] = function(info) {
    return "customFields.productFamily:" + productFamily;
  };
</script>

When embedding Velocity variables into JavaScript strings, ensure the variable values do not contain characters that would break JavaScript syntax (quotes, backslashes, newlines). Use $esc.javascript($value) if the Velocity EscapeTool is available, or validate that custom field values contain only safe characters.

PDF Export Configuration Properties

The PDF export configuration service manages loading of the risksheetPdfExport.vm template:

Property	Type	Default	Description
`risksheetPdfExport.vm`	`string`	`risksheetPdfExport.vm`	Name of the Velocity template file containing PDF export configuration. Attached to Polarion documents to customize PDF export behavior per document or project.
`pdfExportConfiguration`	`string`	None	The full content of the PDF export Velocity template as a string. Contains the script/configuration that controls how Risksheet data is exported to PDF format.
`templateName`	`string`	None	Name of the template used for PDF export configuration. Set when the configuration is loaded from a template.
`fromTemplate`	`boolean`	`false`	Flag indicating whether the PDF export configuration was loaded from a template rather than directly from a document attachment.
`configPath`	`string`	None	File system or repository path to the sheet configuration. Indicates where the PDF export configuration Velocity template is stored.
`fileName`	`string`	None	Name of the sheet configuration. Used to track which file contains the PDF export configuration.

Project Template Installation

Risksheet ships with predefined project templates that can be installed via the administration interface:

Template ID	Description	Use Case
`risksheet_template`	Standard Risksheet project template	General FMEA risk analysis with default column layout and severity/occurrence/detection scales
`risksheet_templateHara`	HARA-specific project template	Hazard Analysis and Risk Assessment (HARA) workflows per ISO 26262

Installation Properties

Property	Description
Installation endpoint	`POST /admin/setup`
Duplicate detection	System automatically checks if `risksheet_template` is already installed before attempting installation
Overwrite behavior	Re-installing templates deletes existing template data first, then uploads fresh versions
Transaction safety	Installation is wrapped in database transactions with automatic rollback on failure
Environment detection	Automatically detects development vs. production environment and loads template files from appropriate locations
Multi-template support	Template ZIP files can contain multiple templates, each identified by a `template.properties` file in its directory root

Re-installing templates overwrites previous versions completely. The system removes old template data before uploading new versions to ensure a clean state. Back up any customizations made to installed templates before re-running setup.

Runtime Configuration Properties

When templates are loaded at runtime, the application exposes version and configuration metadata through the window context:

Property	Type	Source	Description
`version`	`string`	`risksheet.version`	Full version string of the Risksheet application including build metadata
`shortVersion`	`string`	`risksheet.shortVersion`	Shortened version identifier without build metadata for display
`baseUrl`	`string`	`risksheet.baseUrl`	Base URL for the Risksheet application, used to construct API endpoints
`projectId`	`string`	`risksheet.projectId`	Polarion project identifier used in API endpoint construction
`revision`	`string`	`risksheet.revision`	Document revision identifier; empty string indicates head revision, non-empty forces read-only mode
`currentRevision`	`string`	`risksheet.currentRevision`	Latest revision number of the document
`canAdmin`	`boolean`	`risksheet.canAdmin`	Whether the current user has administrative privileges to modify configuration
`configEditUrl`	`string`	Constructed	URL to the Risksheet configuration editor: `${baseUrl}/risksheet/configuration/`
`documentUrl`	`string`	Constructed	Direct URL to the source Polarion document in the standard Polarion UI
`source`	`string`	Configuration	Path to configuration source file (document or template) used to load the current configuration
`templateName`	`string`	Configuration	Name of the template when configuration is loaded from a global template rather than document-specific config

Error Handling

Error Type	Template	Behavior
Velocity syntax error	Top panel	Error details rendered as red HTML message box in the panel area
Velocity syntax error	PDF export	Export fails with error message in the export output
Missing template variable	All	Empty string rendered (Velocity default quiet reference behavior)
Template file not found	Top panel	Default empty panel displayed
Template file not found	PDF export	Export uses default behavior or fails gracefully
Runtime exception (e.g., `StringIndexOutOfBoundsException`)	All	Red error message box with exception details; typically caused by misconfigured template or sheet configuration
`UnsupportedOperationException` for `renderingLayouts`	All	Non-functional log error; fixed in Risksheet 24.7.0+

When a Velocity template error occurs, the error message is rendered directly in the panel or export output. Check the Polarion server logs for the full stack trace. Common causes include misconfigured risksheetTopPanel.vm files and references to document custom fields that do not exist.

Complete Example

A top panel template that extracts a document custom field and registers a queryFactory function for filtering linked items by product family:

## risksheetTopPanel.vm
## Extract document-level custom fields using Polarion API
#set($productFamily = $doc.getOldApi().getValue("productFamily"))
#set($riskOwner = $doc.getOldApi().getValue("riskOwner"))
#set($projectName = $document.projectId)

<div class="risksheet-top-panel" style="padding: 8px; background: #f5f5f5; border-bottom: 1px solid #ddd;">
  <span><strong>Product Family:</strong> $!{productFamily}</span>
  <span style="margin-left: 16px;"><strong>Risk Owner:</strong> $!{riskOwner}</span>
  <span style="margin-left: 16px;"><strong>Project:</strong> $projectName</span>
</div>

<script>
  // Bridge server-side document data to client-side queryFactory
  var _productFamily = "$!{productFamily}";

  // Register queryFactory for filtering linked items by product family
  window.risksheet = window.risksheet || {};
  window.risksheet.queryFactories = window.risksheet.queryFactories || {};
  window.risksheet.queryFactories["filterByFamily"] = function(item) {
    if (_productFamily) {
      return "customFields.productFamily:" + _productFamily;
    }
    return "";
  };
</script>

This pattern demonstrates:

Accessing document custom fields with $doc.getOldApi().getValue()
Rendering server-side data into HTML for display
Passing server-side values to client-side JavaScript variables
Registering a queryFactory function that uses document-level context to filter which items are available for linking in Risksheet columns

A column references the registered factory by name through its typeProperties.queryFactory property in the sheet configuration:

columns:
  - bindings: linkedRequirement
    header: Linked Requirement
    type: itemLink
    typeProperties:
      queryFactory: "filterByFamily"

​Template Files

​Template Resolution Properties

​Velocity Context Variables

​Common Context (All Templates)

​Top Panel Template Context (risksheetTopPanel.vm)

​PDF Export Template Context (risksheetPdfExport.vm)

​Velocity Syntax Reference

​Variables and Properties

​Directives

​Embedding JavaScript in Velocity

​PDF Export Configuration Properties

​Project Template Installation

​Installation Properties

​Runtime Configuration Properties

​Error Handling

​Complete Example

​See Also

Template Files

Template Resolution Properties

Velocity Context Variables

Common Context (All Templates)

Top Panel Template Context (`risksheetTopPanel.vm`)

PDF Export Template Context (`risksheetPdfExport.vm`)

Velocity Syntax Reference

Variables and Properties

Directives

Embedding JavaScript in Velocity

PDF Export Configuration Properties

Project Template Installation

Installation Properties

Runtime Configuration Properties

Error Handling

Complete Example

See Also