Customize the Top Panel

Referred to as the Risksheet attributes panel in the Nextedy Support Portal. Aliases: attributes panel, risksheet attributes panel.

The attributes panel in the Risksheet header showing the document's custom fields above the grid

Why a Separate Top Panel? The Two-File Pattern

Risksheet splits configuration across two files:

File	Role
Sheet configuration (columns, levels, formulas)	Declarative — WHAT to show. Auditable structure, easy to diff.
Top panel configuration (`risksheetTopPanel.vm`)	Imperative — HOW to compute and render. Velocity + JavaScript, code-reviewed.

This separation matters for regulated industries: when a risk matrix changes, only the top panel changes, so the declarative sheet configuration stays untouched and the change-control scope stays small. Tooling can validate the sheet configuration without parsing JavaScript, and the same sheet structure can pair with different calculation strategies by swapping the top panel. For regulated environments, keep formula wrappers in the sheet configuration thin (for example, initialRE: "(info) => { return getInitialRE(info); }") and put the real logic in risksheetTopPanel.vm.

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

Create a new file named risksheetTopPanel.vm
Write your Velocity template content (see examples below)
Attach the file to your Risksheet document or its template document

The recommended way to edit the top panel is directly from the Risksheet interface, via Menu > Configuration > Edit Top Panel Configuration:

Menu > Configuration > Edit Top Panel Configuration in the Risksheet interface

The built-in top-panel configuration editor; save and reload to apply the changes

Alternatively, you can access the top-panel file from the document’s attachments. Open Menu > Document > Open Live Document and find the Attachments section:

Menu > Document > Open Live Document leading to the Attachments section that holds the top-panel file

Downloading, editing, and re-uploading the top-panel file from the document attachments

Risksheet renders the Velocity template as HTML and inserts it above the grid. The template has access to these Velocity context variables:

Variable	Description
`$document`	The current Polarion document object
`$doc`	Alias for the document with access to the old API
`$transaction`	The current Polarion transaction
`$securityService`	Polarion security service (current user, roles)
`$velocityTools`	Standard Velocity tools

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>
  #set($productFamily = $doc.getOldApi().getValue("productFamily"))
  window.risksheetContext = {
    productFamily: "$productFamily"
  };
</script>

Then reference the value in your sheet configuration formula:

formulas:
  filterByFamily: "function(info) { return window.risksheetContext.productFamily; }"

This is the canonical externalization pattern: the sheet configuration declares a named formula; the actual logic lives in the top panel script block. Only the top panel changes when the calculation evolves. 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 from a column in your sheet configuration:

columns:
  - bindings: linkedWorkItems
    header: Requirements
    type: itemLink
    typeProperties:
      queryFactory: filterByProductFamily

Note bindings (plural) — this is the correct property name for the Polarion field mapping on a column.

queryFactory only takes effect inside the column’s typeProperties block (alongside linkRole/linkTypes). A queryFactory placed as a top-level column property is silently ignored — the engine neither keeps it nor moves it, so the filter never applies.

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

Open the Risksheet document
Verify the top panel area displays your custom content above the grid
Check that document custom fields render their current values
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.

Why a Separate Top Panel? The Two-File Pattern

Prerequisites

Step 1: Create the Top Panel Template

Step 2: Display Document Custom Fields

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

Step 4: Filter Item Suggestions Using Top Panel Data

Maximize and Restore the Grid

Error Handling

Step 5: Verify the Top Panel

See Also

​Why a Separate Top Panel? The Two-File Pattern

​Prerequisites

​Step 1: Create the Top Panel Template

​Step 2: Display Document Custom Fields

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

​Step 4: Filter Item Suggestions Using Top Panel Data

​Maximize and Restore the Grid

​Error Handling

​Step 5: Verify the Top Panel

​See Also

Why a Separate Top Panel? The Two-File Pattern

Prerequisites

Step 1: Create the Top Panel Template

Step 2: Display Document Custom Fields

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

Step 4: Filter Item Suggestions Using Top Panel Data

Maximize and Restore the Grid

Error Handling

Step 5: Verify the Top Panel

See Also