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., risksheet.json)
Name of the configuration file 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.
All Risksheet Velocity templates receive a context containing Polarion services, document objects, and utility tools. The available context variables depend on the template type.
## 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}
## 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")
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"; // Define a queryFactory function that uses server-side data function filterByProductFamily(item) { 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.
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 configuration file. Indicates where the PDF export configuration Velocity template is stored.
fileName
string
None
Name of the configuration file. Used to track which file contains the PDF export configuration.
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.
Red error message box with exception details; typically caused by misconfigured template or risksheet.json
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.
