Skip to main content

​
Template Overview

Template FilePurposeAccess LevelUse Case
risksheetTopPanel.vmCustomize header UI panel above the gridRead/Write contextDisplay document metadata, custom fields, buttons, filters
risksheetPdfExport.vmConfigure PDF export behavior and formattingRead-only contextCustom PDF layouts, styling, conditional content
risksheetRenderer.vmCustom cell rendering for grid columnsRead-only contextComplex data visualization, formatted output
risksheetConfig.vmDynamic configuration propertiesRead/Write contextConditional configuration based on document state

​
Available Velocity Context

​
Document Context

The following objects are available in all Velocity templates:
VariableTypeDescriptionAvailable In
$documentcom.nextedy.risksheet.model.DocumentCurrent document object with access to custom fields and metadataAll templates
$docRisksheetPolarionServiceImpl.wrapDocument()Wrapped document with enhanced Polarion integrationAll templates
$documentIdjava.lang.StringFull document ID in format spaceId/documentIdAll templates
$projectIdjava.lang.StringCurrent project identifierAll templates
$txcom.polarion.alm.shared.api.transaction.ReadOnlyTransactionRead-only transaction for accessing Polarion dataAll templates
$transactionReadOnlyTransactionAlias for $txAll templates

​
Polarion Services

Legacy Polarion API services are available for backward compatibility and advanced use cases:
ServiceTypeDescriptionPurpose
$trackerServiceITrackerServiceAccess to work items, projects, and tracking dataQuery work items, enumerate types, access project structure
$securityServiceISecurityServiceUser authentication and permission checksVerify user permissions, check access rights
$txServiceITransactionServiceTransaction managementCreate read-write transactions for operations
$repositoryServiceIRepositoryServiceAccess to project repositories and filesLoad external configuration files, access version control data

​
Utility Objects

UtilityTypeDescriptionExample
$gsoncom.google.gson.GsonJSON serialization/deserialization$gson.toJson($data)
$objectFactoryObjectFactoryFactory for creating Polarion objectsProgrammatic object creation
$escEscapeToolHTML and XML escaping utilities$esc.html($unsafe_text)
$currentDatejava.util.DateCurrent system date and timeDate-based conditional logic
$calendarjava.util.CalendarCalendar utilities for date manipulationAdd days, calculate date ranges

​
Document Custom Fields Access

Access document-level Polarion custom fields through the document context: 
## Access document custom fields
#set($itemField = $!document.customFields.item)
#set($ownerField = $!document.customFields.owner)
#set($versionField = $!document.customFields.version)
#set($modelField = $!document.customFields.model)
#set($teamField = $!document.customFields.team)
#set($lastUpdated = $!document.updated)

## Safely render custom fields (use $! to suppress null errors)
<div class="document-metadata">
  <p>Item: $!itemField</p>
  <p>Owner: $!ownerField</p>
  <p>Model: $!modelField</p>
</div>
Always use $!variable (silent reference) instead of $variable to prevent rendering errors when fields are null or undefined. This prevents error messages from appearing in the rendered output.

​
Loading External Configuration

​
Repository File Access Pattern

Load external XML or JSON configuration files from project repositories: 
## Example: Load risk matrix configuration from repository
#set($repoService = $repositoryService)
#set($project = $trackerService.getProject($projectId))

## Access repository using Polarion APIs
#set($repository = $project.getRepository())
#set($filePath = "config/risk-matrix.xml")

## Read file content (requires read transaction)
#set($fileContent = $repository.getFile($filePath))
#if($fileContent)
  ## Parse XML or process file content
  #set($riskMatrix = $gson.fromJson($fileContent, "Object.class"))
#end
Minimize file I/O operations in templates. Large file reads or multiple repository calls can impact page load time. Consider caching loaded configurations in Polarion document attachments when possible.

​
Multi-Level Linked Item Patterns

​
Accessing Nested Linked Items

For templates that need to display multi-level work item hierarchies: 
## Access items linked to the current item
#set($linkedItems = $item.getLinkedItems())

## Iterate through linked items
#foreach($linkedItem in $linkedItems)
  ## Access fields of linked item
  <div class="linked-item">
    <span>ID: $linkedItem.id</span>
    <span>Title: $linkedItem.title</span>
    
    ## Access items linked to the linked item (two levels)
    #set($nestedItems = $linkedItem.getLinkedItems())
    #foreach($nestedItem in $nestedItems)
      <div class="nested-item">
        ID: $nestedItem.id
      </div>
    #end
  </div>
#end

​
Configuration Property References

​
Top Panel HTML Structure

The top panel renders as a div above the RISKSHEET grid. Use semantic HTML with CSS classes for styling: 
<div class="rs-top-panel">
  <div class="rs-row">
    <div class="rs-label">Item:</div>
    <div class="rs-value">$!document.customFields.item</div>
    <div class="rs-label">Status:</div>
    <div class="rs-value">$!document.customFields.status</div>
  </div>
  <div class="rs-row">
    <div class="rs-label">Owner:</div>
    <div class="rs-value">$!document.customFields.owner</div>
    <div class="rs-label">Updated:</div>
    <div class="rs-value">$!document.updated</div>
  </div>
</div>

​
Error Handling

​
Template Errors Display

Errors in Velocity templates render as red message boxes in the top panel area: 
## Prevent template errors with defensive coding
#if($document && $document.customFields)
  ## Safe to access custom fields
  Item: $!document.customFields.item
#else
  <span class="error">Document context unavailable</span>
#end
Error TypeCauseResolution
Syntax errorInvalid Velocity syntaxValidate VTL syntax in editor
Null referenceAccessing undefined variableUse $!variable syntax
Type mismatchCalling wrong method on objectCheck object type documentation
Permission deniedInsufficient access to serviceVerify user permissions
File not foundRepository file doesn’t existVerify file path and repository

​
Template Editing

​
Built-in Configuration Editor (v25.5.0+)

Edit Velocity templates directly in the RISKSHEET interface:
  1. Open RISKSHEET document
  2. Click Menu > Configuration > Edit Top Panel Configuration…
  3. Edit template with syntax highlighting
  4. Save changes (applied immediately on page reload)

​
Manual File Editing

For templates not supported in the built-in editor:
  1. Open Polarion document in LiveDoc
  2. Navigate to document Attachments section
  3. Download template file (e.g., risksheetTopPanel.vm)
  4. Edit in text editor
  5. Upload modified file back to document

​
Common Template Patterns

​
Display Document Metadata Panel

<div class="metadata-panel">
  <h3>Document Information</h3>
  <table>
    <tr>
      <td>ID:</td>
      <td>$!document.customFields.item</td>
    </tr>
    <tr>
      <td>Owner:</td>
      <td>$!document.customFields.owner</td>
    </tr>
    <tr>
      <td>Last Updated:</td>
      <td>$!document.updated</td>
    </tr>
  </table>
</div>

​
Conditional Rendering Based on Status

#set($status = $!document.customFields.status)
#if($status == "Draft")
  <div class="alert-warning">This document is still in draft status</div>
#elseif($status == "Review")
  <div class="alert-info">Document is awaiting review approval</div>
#elseif($status == "Published")
  <div class="alert-success">Document is published and active</div>
#end

## Create links to related documents
#set($relatedDocId = $!document.customFields.relatedDoc)
#if($relatedDocId)
  <a href="/risksheet/document/$projectId/$relatedDocId">View Related Document</a>
#end

​
Version Information

  • Minimum Version: RISKSHEET 25.0.0
  • Enhanced Editor: RISKSHEET 25.5.0+ (built-in Velocity template editor)
  • Velocity Engine: Apache Velocity 2.0+
  • Polarion API: Compatible with Polarion 22.2+

​
Best Practices

  • Do: Use silent references ($!) for safety
  • Do: Validate objects before accessing methods
  • Do: Minimize repository/API calls
  • Do: Cache frequently accessed data
  • Do: Escape user-provided content
  • Do: Test templates with varied document states
  • Do: Document custom field names in comments
  • Don’t: Use deeply nested loops (performance)
  • Don’t: Expose sensitive Polarion APIs
  • Don’t: Perform large file I/O in top panel
KB ArticlesSupport TicketsSource Code
  • PdfExportConfigurationService.java
  • AppConfig.ts
  • RisksheetViewServlet.java
  • AppConfigParser.ts
  • RisksheetSetupService.java