Formula Syntax - Nextedy Documentation

Formula Definition

Configuration Location

Formulas are defined in two places within sheet configuration:

Location	Type	Description
`formulas`	`object`	Top-level named formula definitions. Keys are formula names, values are JavaScript function strings.
`columns[].formula`	`string`	Inline formula on a specific column. References a named formula or contains a direct function string.

Function Signature

Every formula function follows this pattern:

function(info) {
  // info.item - the current row's data object
  // info.value - the current cell value
  // info.cell  - the DOM element of the cell
  // return the computed value
}

Parameter	Type	Description
`info.item`	`object`	The current row’s work item data. Access fields via `info.item['fieldId']`.
`info.value`	`any`	The current stored value of the cell before formula execution.
`info.cell`	`HTMLElement`	The DOM element representing the cell. Used for direct DOM manipulation in advanced scenarios.

Accessing Item Properties

Use bracket notation to access work item field values:

function(info) {
  var severity = info.item['sev'];
  var occurrence = info.item['occ'];
  var detection = info.item['det'];
  return severity * occurrence * detection;
}

Enum Values Are IDsWhen accessing enum fields, info.item['fieldId'] returns the enum ID (e.g., "yes"), not the display name (e.g., "Y"). Always compare against enum IDs in formula logic.

Field Access Patterns

Pattern	Description
`info.item['fieldId']`	Access a direct field on the current work item
`info.item['linkedField_link']`	Access the HTML link for an item link column (using the `_link` suffix)
`info.item['systemItemId']`	Access the Polarion work item ID
`info.item['systemReadOnly']`	Check if the item is read-only

Return Values

Return Type	Behavior
`number`	Displayed as a numeric value in the cell
`string`	Displayed as text in the cell
`null`	Cell displays as empty
`undefined`	Cell displays as empty

Null-Safe CalculationsAlways guard against null or undefined values. When multiplying risk parameters, return null for empty inputs to avoid displaying NaN or 0:

function(info) {
  var value = info.item['occ'] * info.item['det'] * info.item['sev'];
  return value ? value : null;
}

Named vs. Inline Formulas

Named Formulas

Define reusable formulas in the top-level formulas object, then reference by name in column definitions:

formulas:
  commonRpn: function(info){ var value = info.item['occ']*info.item['det']*info.item['sev'];
    return value?value:null;}
columns:
- id: rpn
  header: RPN
  formula: commonRpn

Inline Formulas

Define the formula directly on the column:

columns:
- id: rpn
  header: RPN
  formula: function(info){ return info.item['occ']*info.item['det']*info.item['sev'];
    }

Formula Execution Behavior

Behavior	Description
Execution timing	Formulas are evaluated when the document is opened or reloaded, when a row is created or edited, and when Check stored formulas runs
Read-only	Columns with `formula` are automatically set to `readOnly: true`
Hidden columns	Column visibility does not affect execution. Since v26.7.1, a formula column is evaluated whether or not it is shown in the active view, and the columns feeding it may be hidden as well.
Change tracking	When formula results differ from stored values, the system can mark the item as edited
Persistence	Calculated values are written to the bound Polarion field for columns with `readOnly: false`, as part of saving a created or edited row. Check stored formulas marks every row whose stored value drifted, so the next save rewrites them too. Opening a document recalculates and displays values without writing them back.

Displaying a Value and Storing It Are SeparateOpening a document recalculates every formula and shows current values, but does not rewrite stored data. Values reach Polarion when you save the document — for rows that were created or edited, or that Check stored formulas marked as drifted. Formulas and Column Visibility covers the full rule, including the behavior on versions earlier than v26.7.1.

Bridging Top Panel Functions

For complex calculations, define JavaScript functions in the risksheetTopPanel.vm file and call them from sheet configuration formulas:

// In risksheetTopPanel.vm <script> section:
function calculateRiskLevel(info) {
  var sev = info.item['severity'];
  var prob = info.item['probability'];
  // Complex risk matrix lookup
  if (sev >= 8 && prob >= 6) return 'Unacceptable';
  if (sev >= 5 && prob >= 4) return 'Further Investigation';
  return 'Acceptable';
}

formulas:
  riskLevel: function(info){ return calculateRiskLevel(info); }

Accessing Document Custom FieldsDocument-level custom fields can be accessed via $doc.getOldApi().getValue('customFieldID') in the risksheetTopPanel.vm script section, then referenced from sheet configuration formulas through top panel functions.

Check Stored Formulas

When formula columns have readOnly: false, or when items are imported without formula execution, use Menu > Rows > Check stored formulas (available since v24.5.1) to reconcile formula values between Polarion and Risksheet.

Complete Example

formulas:
  commonRpn: function(info){ var value = info.item['occ']*info.item['det']*info.item['sev'];
    return value?value:null;}
  commonRpnNew: function(info){ var value = info.item['occNew']*info.item['detNew']*info.item['sevNew'];
    return value?value:null; }
columns:
- id: sev
  header: Severity
  type: rating:severity
- id: occ
  header: Occurrence
  type: rating:occurrence
- id: det
  header: Detection
  type: rating:detection
- id: rpn
  header: RPN
  type: int
  formula: commonRpn
- id: sevNew
  header: Severity (New)
  type: rating:severity
- id: occNew
  header: Occurrence (New)
  type: rating:occurrence
- id: detNew
  header: Detection (New)
  type: rating:detection
- id: rpnNew
  header: RPN (New)
  type: int
  formula: commonRpnNew

Formula Functions — built-in helper functions for formulas
Formula Examples — ready-to-use formula patterns
Calculated Columns — column configuration for calculated fields
Cell Decorators — conditional styling driven by formula values
Top Panel Template — defining helper functions in the top panel

​Formula Definition

​Configuration Location

​Function Signature

​Accessing Item Properties

​Field Access Patterns

​Return Values

​Named vs. Inline Formulas

​Named Formulas

​Inline Formulas

​Formula Execution Behavior

​Bridging Top Panel Functions

​Check Stored Formulas

​Complete Example

​Related Pages

Formula Definition

Configuration Location

Function Signature

Accessing Item Properties

Field Access Patterns

Return Values

Named vs. Inline Formulas

Named Formulas

Inline Formulas

Formula Execution Behavior

Bridging Top Panel Functions

Check Stored Formulas

Complete Example

Related Pages