Skip to main content

​
Prerequisites

  • Administrator privileges for the Polarion project
  • Familiarity with Velocity template syntax
  • A Risksheet document or template where you can attach files

​
Step 1: Create the Top Panel Template

  1. Create a new file named risksheetTopPanel.vm
  2. Write your Velocity template content (see examples below)
  3. Attach the file to your Risksheet document or its template document
Risksheet renders the Velocity template as HTML and inserts it above the grid. The template has access to these Velocity context variables:
VariableDescription
$documentThe current Polarion document object
$docAlias for the document with access to the old API
$transactionThe current Polarion transaction
$velocityToolsStandard Velocity tools
diagram

​
Step 2: Display Document Custom Fields

Show document-level custom fields in the top panel using Velocity expressions: 
<div class="risksheet-panel-info">
  <strong>Product Family:</strong> $document.customFields.productFamily
  <strong>Status:</strong> $document.customFields.approvalStatus
</div>
For custom fields that require the old API: 
#set($productFamily = $doc.getOldApi().getValue("productFamily"))
<div class="risksheet-panel-info">
  <strong>Product Family:</strong> $productFamily
</div>
The top panel can display document custom fields but cannot modify them directly. Custom fields must be updated through Polarion’s standard document editing interface.

​
Step 3: Bridge Server-Side Data to Client-Side Formulas

Use the top panel to extract server-side data and make it available to client-side JavaScript. This is essential for formulas and query factories that need document-level context: 
<script>
  // Extract document custom field value via Velocity
  #set($productFamily = $doc.getOldApi().getValue("productFamily"))

  // Make it available to risksheet.json formulas
  window.risksheetContext = {
    productFamily: "$productFamily"
  };
</script>
Then reference the value in your risksheet.json formula: 
{
  "formulas": {
    "filterByFamily": "function(info) { return window.risksheetContext.productFamily; }"
  }
}

​
Step 4: Filter Item Suggestions Using Top Panel Data

Combine the top panel Velocity script with a queryFactory function to dynamically filter linked items based on document-level custom field values: 
<script>
  #set($productFamily = $doc.getOldApi().getValue("productFamily"))

  // Register a custom query factory
  window.risksheet = window.risksheet || {};
  window.risksheet.queryFactories = window.risksheet.queryFactories || {};
  window.risksheet.queryFactories.filterByProductFamily = function(query) {
    return query + ' AND customField.productFamily:"$productFamily"';
  };
</script>
Then reference this query factory in your column configuration: 
{
  "columns": [
    {
      "binding": "linkedWorkItems",
      "header": "Requirements",
      "type": "itemLink",
      "queryFactory": "filterByProductFamily"
    }
  ]
}
The top panel Velocity template runs on the server side, extracting document field values. It outputs JavaScript variables into the page. Client-side formulas and query factories then read those variables at runtime. This server-to-client bridge is the standard pattern for document-aware filtering.

​
Maximize and Restore the Grid

The top panel includes a built-in toggle to maximize the grid viewing area:
  • Click the maximize button to hide the top panel and expand the grid to full height
  • Click the restore button to show the top panel again
This toggle is always available and requires no configuration.

​
Error Handling

If the Velocity template contains errors, Risksheet renders a red message box in the top panel area. Common errors include:
  • Syntax errors in Velocity — missing #end directives or undefined variables
  • Missing custom field — referencing a document custom field that does not exist returns null
  • JavaScript errors — check the browser console for client-side script issues
The risksheetTopPanel.vm file follows the same inheritance rules as risksheet.json. Risksheet first checks the current document, then searches the document’s template hierarchy. If you use Override Template Configuration, you can have a document-specific top panel that differs from the template.

​
Step 5: Verify the Top Panel

After attaching or updating your risksheetTopPanel.vm:
  1. Open the Risksheet document
  2. Verify the top panel area displays your custom content above the grid
  3. Check that document custom fields render their current values
  4. If using JavaScript bridging, open the browser console and verify window.risksheetContext (or your variable name) contains the expected data
You should now see your custom top panel content displayed above the Risksheet grid.

​
See Also

KB ArticlesSupport TicketsSource Code
  • MaximizeViewCommand.ts
  • RisksheetViewServlet.java
  • ShowConfigurationCommand.ts
  • AppConfig.ts
  • RisksheetProjectProperties.java