Top Panel Template - Nextedy Documentation

Template File and Loading

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 the sheet configuration. See Template Path Configuration for the lookup order.

Three-File Architecture: Declarative Config vs Custom Logic

Risksheet uses three distinct configuration files, each with a different role and change-management profile. Understanding this separation is critical for regulated industries (medical devices, automotive, aerospace):

Layer	File	Content Type	Change Impact
Declarative config	sheet configuration (`risksheet.json`)	WHAT to show: columns, levels, dataTypes, styles	Auditable structure, auto-validatable, easy to diff
Custom logic	top panel configuration (`risksheetTopPanel.vm`)	HOW to compute: risk matrices, conditional formatting, formula helpers	Custom code, requires code review
Export formatting	PDF export configuration (`risksheetPdfExport.vm`)	HOW to print: PDF layout, cover pages	Presentation layer

Why Externalize JavaScript to the Top Panel?

This separation simplifies change management in regulated industries:

Validation scope — When the risk matrix changes (for example, severity thresholds updated), only the top panel changes. The sheet configuration (which defines grid structure) is untouched, narrowing the validation scope for change control.
Auditability — The sheet configuration is a declarative artifact. Tools can automatically verify its structure (correct property names, valid enum references, level consistency) without parsing JavaScript.
Template reuse — The same sheet configuration structure can work with different calculation strategies by swapping the top panel. For example, one top panel implements a 2D risk matrix (severity x occurrence to classification); another implements a 3D RPN calculation (S x O x D to numeric score).
Separation of concerns — Configuration authors (risk managers) define WHAT columns exist and how data flows. Script authors (developers, validation engineers) define HOW values are calculated. Different competencies, different review gates.

Recommended pattern: in the sheet configuration, keep formulas entries as thin wrappers that delegate to functions defined in the top panel. Example:

formulas:
  initialRE: "(info) => { return getInitialRE(info); }"

The full getInitialRE implementation lives in the top panel <script> block, alongside risk matrix logic and any jQuery-based cell decorators. In-line formulas in the sheet configuration are acceptable for simple calculations (for example, RPN = S * O * D); complex logic (risk matrices, multi-field conditional formatting) should be externalized to the top panel.

Template Structure

A typical risksheetTopPanel.vm file contains three sections:

Section	Purpose	Example
`<style>` block	CSS rules for panel layout, image sizing, and custom classes	`.rs-top-panel-info { padding: 8px; }`
HTML markup	Document metadata display, action buttons, filter controls	`<div>Product: $!productFamily</div>`
`<script>` block	JavaScript functions for formulas, query factories, and context menu actions	`function calcRisk(info) { ... }`

## Velocity comments start with ##

## 1. CSS styling
<style>
  .panel-info { display: flex; gap: 16px; padding: 8px; }
</style>

## 2. HTML content
<div class="panel-info">
  <span>Document: $doc.moduleNameWithSpace</span>
</div>

## 3. JavaScript functions
<script>
  function myFormulaHelper(info) {
    return info.item['sev'] * info.item['occ'];
  }
</script>

Velocity Context Variables

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
`$securityService`	`ISecurityService`	Polarion security service for current user and role lookup

$securityService — Role-Based UI

The $securityService is available in top panel Velocity and exposes the current user and that user’s roles. Use it to drive role-based default views, conditional rendering, and permission-aware UI:

Method	Returns	Description
`getCurrentUser()`	user object	The currently authenticated Polarion user
`getRolesForUser(user)`	list of role names	The roles assigned to the given user

#set($currentUser = $securityService.getCurrentUser())
#set($userRoles = $securityService.getRolesForUser($currentUser))

<script>
  var currentUserRoles = [
  #foreach($role in $userRoles)
    "$role"#if($foreach.hasNext),#end
  #end
  ];

  // Example: select a default view based on user role
  window.risksheet = window.risksheet || {};
  if (currentUserRoles.indexOf("safety_reviewer") >= 0
      && risksheet.appConfig && risksheet.appConfig.views) {
    // Reviewers see the "Final Risk Assessment" view by default
    risksheet.appConfig.views.forEach(function(v) {
      v.defaultView = (v.name === "Final Risk Assessment");
    });
  }
</script>

Typical use cases: showing reviewer-only filters, hiding administrative buttons from end users, and selecting an appropriate saved view per role.

Accessing Document Custom Fields

There are two approaches to reading document-level custom fields in the top panel.

Method 1: $doc.getOldApi().getValue()

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>

Method 2: $document.customFields

Use $document.customFields.fieldName for direct display in HTML markup:

<div class="rs-top-panel-info">
  <span>Product Family: $!document.customFields.productFamily</span>
  <span>Risk Matrix: $!document.customFields.riskMatrixVersion</span>
</div>

$!document.customFields.<field> renders the document custom-field value correctly in the top panel template — the shipped Risksheet top panels rely on it (for example $!document.customFields.item, owner, version, model, team). This differs from a standard Polarion page Velocity context, where $document.customFields may print empty and $document.getValue('id') is the usual form. In the top panel, both Method 1 and Method 2 above are valid; use $! (with the exclamation mark) to suppress null-reference output for optional fields.

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.

Bridging Server Data to Client-Side Formulas

The primary use case for the top panel template is defining JavaScript functions that sheet configuration formulas can call. This bridges server-side Polarion data (accessible via Velocity) into client-side formula execution.

Pattern

Step 1. Define a JavaScript function in risksheetTopPanel.vm using Velocity to inject server-side data:

#set($matrixData = $doc.getOldApi().getValue('riskMatrix'))
<script>
  var riskMatrix = $matrixData;

  function getRiskAcceptance(severity, occurrence) {
    return riskMatrix[severity][occurrence];
  }
</script>

Step 2. Reference the top panel function from a formula in the sheet configuration:

formulas:
  riskAcceptance: "function(info) { return getRiskAcceptance(info.item['severity'], info.item['occurrence']); }"

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.

Reading Downstream Task Data with risksheet.ds.getDownstreamRows

For formulas that need access to downstream task work items linked from the current risk row, the client-side data source exposes risksheet.ds.getDownstreamRows(riskId). This is useful for aggregating values across mitigation tasks, computing initial-vs-residual risk indices, or iterating over multi-round assessments.

function getInitialRiskIndex(info) {
  var riskId = info.item["systemItemId"];
  var tasks = risksheet.ds.getDownstreamRows(riskId);

  var det = 0;
  tasks.forEach(function(t) {
    // Direct field access on task objects
    var round = t.round;
    var rcm = t.RCMdet;

    // Filter by enum string value
    if (round === "initial") {
      // Enum underscore-to-decimal pattern: "0_1" -> 0.1
      det = parseFloat((rcm || "0_0").replace("_", "."));
    }
  });

  // Read another formula's stored result via info.item
  return det * info.item['ri'];
}

Pattern	Details
`risksheet.ds.getDownstreamRows(riskId)`	Returns an array of task objects linked downstream from the risk identified by `riskId`
`t.fieldId`	Direct field access on each task object (for example, `t.RCMdet`, `t.round`)
Enum underscore-to-decimal	Enum values are stored with underscore for decimals: `"0_1"` becomes `0.1` via `replace("_", "."); parseFloat(...)`
`info.item['columnId']`	A formula can read another formula’s stored result on the same row through `info.item`

This API enables risk roll-ups and cross-row aggregations that would otherwise require server-side rendering or custom Velocity macros.

Dynamic Risk Matrices from External Sources

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 sheet configuration:

#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 sheet configuration 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.

Filtering Linked Items with Query Factory

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):

#set($productFamily = $doc.getOldApi().getValue('productFamily'))
<script>
  var documentProductFamily = "$!productFamily";

  window.risksheet = window.risksheet || {};
  window.risksheet.queryFactories = window.risksheet.queryFactories || {};
  window.risksheet.queryFactories["filterByProductFamily"] = function(info) {
    return 'type:requirement AND productFamily:' + documentProductFamily;
  };
</script>

Column configuration in the sheet configuration:

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

The query factory function constructs a Lucene query string that filters the item suggester results. The function receives a single info object describing the current row and context.

Enum Type Identifiers

When configuring enum columns, the type property in the sheet configuration 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 the sheet configuration must match exactly.

CSS Styling in the Top Panel

The top panel template can include <style> blocks to control the appearance of the panel content, rich text images, and custom cell rendering:

<style>
  .rs-rich-text-image img {
    max-height: 40px;
    object-fit: contain;
  }
  .rs-top-panel-info {
    display: flex;
    gap: 16px;
    padding: 8px;
    font-size: 13px;
    color: #333;
  }
  .rs-top-panel-info .label {
    font-weight: 600;
    color: #555;
  }
</style>

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.

<script>
  window.myCustomAction = function(item) {
    var projectId = "$!{project.id}";
    // Custom action implementation using server-side data
    alert('Running check for item ' + item.ID + ' in project ' + projectId);
  };

  window.risksheet = window.risksheet || {};
  window.risksheet.customContextMenuActions = [
    {
      label: "Run Custom Check",
      enabled: function(item) { return !item.isNew; },
      execute: function(item) { window.myCustomAction(item); }
    }
  ];
</script>

Each custom context menu action requires three properties:

Property	Type	Description
`label`	`string`	Text displayed in the context menu
`enabled`	`function(item)`	Returns `true` if the action is available for the given item. The function receives the current row’s data object
`execute`	`function(item)`	The action to perform when clicked. The function receives the current row’s data object

Maximize/Restore Toggle

The top panel visibility can be toggled by the user to maximize the grid viewing area. When toggled:

The top panel hides entirely
The grid expands to use the full available space
The toggle button is always available in the toolbar

This is useful when the top panel displays informational content that is not needed during active editing.

Error Handling

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.

Complete Example

A full risksheetTopPanel.vm file for an FMEA document with metadata display, role-aware default view, risk evaluation function, downstream task aggregation, query factory, and a custom context menu action:

## risksheetTopPanel.vm - FMEA document top panel
## Displays product family, matrix version, and document name
## Provides risk evaluation function and filtered item linking

#set($productFamily = $doc.getOldApi().getValue('productFamily'))
#set($riskMatrixVersion = $doc.getOldApi().getValue('riskMatrixVersion'))
#set($currentUser = $securityService.getCurrentUser())
#set($userRoles = $securityService.getRolesForUser($currentUser))

<style>
  .fmea-panel {
    display: flex;
    gap: 16px;
    padding: 8px 12px;
    font-size: 13px;
    background: #f5f5f5;
    border-bottom: 1px solid #ddd;
  }
  .fmea-panel .label {
    font-weight: 600;
    color: #555;
  }
  .fmea-panel .value {
    color: #333;
  }
</style>

<div class="fmea-panel">
  <span><span class="label">Product Family:</span>
    <span class="value">$!productFamily</span></span>
  <span><span class="label">Matrix Version:</span>
    <span class="value">$!riskMatrixVersion</span></span>
  <span><span class="label">Document:</span>
    <span class="value">$doc.moduleNameWithSpace</span></span>
</div>

<script>
  // Server-side data injected via Velocity
  var documentProductFamily = "$!productFamily";
  var currentUserRoles = [
  #foreach($role in $userRoles)
    "$role"#if($foreach.hasNext),#end
  #end
  ];

  // Risk evaluation function called from sheet configuration formulas
  function getRiskLevel(severity, occurrence) {
    var matrix = {
      "high":   { "high": "unacceptable", "medium": "undesirable", "low": "acceptable" },
      "medium": { "high": "undesirable",  "medium": "acceptable",  "low": "acceptable" },
      "low":    { "high": "acceptable",   "medium": "acceptable",  "low": "negligible" }
    };
    return matrix[severity]
      ? (matrix[severity][occurrence] || "unknown")
      : "unknown";
  }

  // Aggregate downstream task data for residual risk computation
  function getResidualRisk(info) {
    var tasks = risksheet.ds.getDownstreamRows(info.item["systemItemId"]);
    var reduction = 0;
    tasks.forEach(function(t) {
      // Enum "0_1" -> 0.1
      if (t.round === "final" && t.RCMdet) {
        reduction += parseFloat(t.RCMdet.replace("_", "."));
      }
    });
    return reduction;
  }

  // Role-based default view selection
  window.risksheet = window.risksheet || {};
  if (currentUserRoles.indexOf("safety_reviewer") >= 0
      && risksheet.appConfig && risksheet.appConfig.views) {
    risksheet.appConfig.views.forEach(function(v) {
      v.defaultView = (v.name === "Final Risk Assessment");
    });
  }

  // Query factory for filtering linked item suggestions by product family
  window.risksheet.queryFactories = window.risksheet.queryFactories || {};
  window.risksheet.queryFactories["filterByProductFamily"] = function(info) {
    return 'type:requirement AND productFamily:' + documentProductFamily;
  };

  // Custom context menu action
  window.risksheet.customContextMenuActions = [
    {
      label: "Evaluate Risk Level",
      enabled: function(item) { return item['severity'] && item['occurrence']; },
      execute: function(item) {
        var level = getRiskLevel(item['severity'], item['occurrence']);
        alert('Risk Level: ' + level);
      }
    }
  ];
</script>

The corresponding sheet configuration formulas reference the top panel functions:

formulas:
  riskLevel: "function(info){ return getRiskLevel(info.item['severity'], info.item['occurrence']); }"
  residualRisk: "function(info){ return getResidualRisk(info); }"
columns:
  - id: riskLevel
    header: Risk Level
    bindings: riskLevel
    formula: riskLevel
  - id: residualRisk
    header: Residual Risk
    bindings: residualRisk
    formula: residualRisk
  - bindings: linkedRequirement
    header: Linked Requirement
    type: itemLink
    typeProperties:
      queryFactory: "filterByProductFamily"

Velocity Template Context — full list of available Velocity context variables
Velocity Templates — Velocity template engine reference and syntax
Custom Renderer Templates — cell display customization templates
PDF Export Template — PDF export Velocity template
Formula Functions — formula patterns that call top panel functions
Customize the Top Panel — step-by-step how-to guide
Configuration Properties Index — all configuration properties

​Template File and Loading

​Three-File Architecture: Declarative Config vs Custom Logic

​Why Externalize JavaScript to the Top Panel?

​Template Structure

​Velocity Context Variables

​$securityService — Role-Based UI

​Accessing Document Custom Fields

​Method 1: $doc.getOldApi().getValue()

​Method 2: $document.customFields

​Bridging Server Data to Client-Side Formulas

​Pattern

​Reading Downstream Task Data with risksheet.ds.getDownstreamRows

​Dynamic Risk Matrices from External Sources

​Filtering Linked Items with Query Factory

​Enum Type Identifiers

​CSS Styling in the Top Panel

​Context Menu Integration

​Maximize/Restore Toggle

​Error Handling

​Complete Example

​Related Pages

Template File and Loading

Three-File Architecture: Declarative Config vs Custom Logic

Why Externalize JavaScript to the Top Panel?

Template Structure

Velocity Context Variables

$securityService — Role-Based UI

Accessing Document Custom Fields

Method 1: $doc.getOldApi().getValue()

Method 2: $document.customFields

Bridging Server Data to Client-Side Formulas

Pattern

Reading Downstream Task Data with risksheet.ds.getDownstreamRows

Dynamic Risk Matrices from External Sources

Filtering Linked Items with Query Factory

Enum Type Identifiers

CSS Styling in the Top Panel

Context Menu Integration

Maximize/Restore Toggle

Error Handling

Complete Example

Related Pages