The template file is named risksheetTopPanel.vm and is stored as a document attachment in Polarion. The /api/panel endpoint loads the file, renders it through the Velocity engine with full access to Polarion services, and returns the resulting HTML. If an error occurs during rendering, a red error message box displays instead of the panel content.
If no risksheetTopPanel.vm file is attached to the current document, Risksheet searches the document’s template hierarchy. The system uses the same configuration inheritance path as risksheet.json. See Template Path Configuration for the lookup order.
The top panel template receives the full Velocity context with access to Polarion services and document data. See Velocity Template Context for the complete reference.
Variable
Type
Description
$doc
IModule
Current Polarion document object. Provides access to document metadata, custom fields, and the module API
$document
Document
Risksheet document wrapper with customFields access for direct field reading
$transaction
ITransaction
Current Polarion transaction for data operations
$trackerService
ITrackerService
Polarion tracker service for work item queries and data retrieval
$projectService
IProjectService
Polarion project service for project-level metadata
Use $doc.getOldApi().getValue('customFieldID') for programmatic access. This is the preferred method when you need to pass values into JavaScript variables:
#set($productFamily = $doc.getOldApi().getValue('productFamily'))#set($riskMatrixVersion = $doc.getOldApi().getValue('riskMatrixVersion'))<script> var documentProductFamily = "$!productFamily"; var matrixVersion = "$!riskMatrixVersion";</script>
The top panel can display document custom fields but cannot modify them. To change document field values, use the standard Polarion document editor. Custom context menu actions for document workflow transitions are not natively supported.
Table-type custom fields can also be accessed via $doc.getOldApi().getValue('customFieldID'). The returned object structure depends on the Polarion table field implementation.
The primary use case for the top panel template is defining JavaScript functions that risksheet.json formulas can call. This bridges server-side Polarion data (accessible via Velocity) into client-side formula execution.
Top panel functions called from formulas receive the same info object. Access work item field values via info.item['fieldId'] and return the result. Prepare all needed values within functions defined in the top panel file.
The top panel can reference external data sources via Velocity context and Polarion APIs, enabling dynamic risk matrix definitions shared across projects without duplicating formula logic in each risksheet.json:
#set($xmlConfig = $trackerService.getDataService().getAttachment($doc, 'risk-matrix.xml'))<script> var riskMatrix = parseRiskMatrix('$!xmlConfig'); function evaluateRiskCondition(severity, occurrence) { return riskMatrix.lookup(severity, occurrence); }</script>
This pattern replaces hardcoded riskCondition formulas in each project’s risksheet.json with a centralized, dynamic matrix definition.
The exact API for loading attachments and external XML files depends on your Polarion version and installed plugins. The pattern above demonstrates the general approach — verify the specific Polarion API calls in your environment.
Combine the top panel template with a query factory function to filter item suggestions based on document-level fields. This is useful when different documents in the same project should only link to items matching their product family or variant:Top panel template (risksheetTopPanel.vm):
The query factory function constructs a Lucene query string that filters the item suggester results. The function receives the column configuration and the current item as parameters.
When configuring enum columns, the type property in risksheet.json must match the enum definition name in Polarion’s custom fields XML. The top panel can help verify or map enum identifiers:
<script> function getEnumDisplayValue(info) { var fieldValue = info.item['riskCategory']; // Map enum ID to display label if needed return fieldValue; }</script>
Check the .polarion/documents/fields/custom-fields.xml file in your project’s SVN repository for the exact enum definition name to use in the type property. The enum type identifier in risksheet.json must match exactly.
When rendering rich text fields with images via server render columns, set the bindings to task.$item rather than the specific field binding. Control image sizing through CSS in the top panel. See Render Custom Data for details.
Custom context menu actions can be registered via window.risksheet.customContextMenuActions in the top panel <script> block. Functions must exist on the global window object.
If the risksheetTopPanel.vm template contains errors (Velocity syntax errors, missing variable references, or JavaScript errors), the panel displays a red error message box instead of the expected content. The grid remains functional even when the top panel fails to render.
If the top panel displays an error, check the Polarion server logs for Velocity rendering errors. Common issues include missing $doc references, undefined custom field IDs, and malformed Velocity syntax. Use $!variable (with exclamation mark) to suppress null reference errors for optional fields.
