Skip to main content

​
Formula Definition

​
Configuration Location

Formulas are defined in two places within risksheet.json:
LocationTypeDescription
formulasobjectTop-level named formula definitions. Keys are formula names, values are JavaScript function strings.
columns[].formulastringInline 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
}
ParameterTypeDescription
info.itemobjectThe current row’s work item data. Access fields via info.item['fieldId'].
info.valueanyThe current stored value of the cell before formula execution.
info.cellHTMLElementThe 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;
}
When 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

PatternDescription
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 TypeBehavior
numberDisplayed as a numeric value in the cell
stringDisplayed as text in the cell
nullCell displays as empty
undefinedCell displays as empty
Always 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

diagram
BehaviorDescription
Execution timingFormulas execute during cell rendering
Read-onlyColumns with formula are automatically set to readOnly: true
Hidden columnsFormula columns do not execute when hidden from the grid view. If a title column uses a formula and is hidden during item creation, the work item will have an incorrect title.
Change trackingWhen formula results differ from stored values, the system can mark the item as edited
PersistenceCalculated values are persisted to Polarion fields when the item is saved
Formula columns do not execute when hidden. If you use a formula for the title field, keep that column visible during item creation. Use Saved Views to manage column visibility for different workflows rather than hiding formula columns.

​
Bridging Top Panel Functions

For complex calculations, define JavaScript functions in the risksheetTopPanel.vm file and call them from risksheet.json 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); }"
  }
}
Document-level custom fields can be accessed via $doc.getOldApi().getValue('customFieldID') in the risksheetTopPanel.vm script section, then referenced from risksheet.json 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"
    }
  ]
}
KB ArticlesSupport TicketsSource Code
  • AppConfig.ts
  • risksheet.json
  • AppConfigHelper.ts
  • CellPreviewFormatter.ts
  • PolarionAppConfigManager.java