Skip to main content

​
Macro Signature

PropertyValue
Macro NamenxRiskMatrix
Librarynextedy_solutions.vm
PurposeRender a severity × likelihood (or other 2D) risk matrix with color-coded cells
Return TypeHTML (rendered directly to page)
ContextRequires Velocity template with item query and risk calculation function

​
Parameters

NameTypeDefaultDescription
$rowValuesArrayRequiredList of row dimension values (e.g., Severity: S1, S2, S3, S4)
$colValuesArrayRequiredList of column dimension values (e.g., Likelihood: L1, L2, L3, L4, L5)
$itemsCollectionRequiredCollection of work items to analyze (usually hazards or failure modes)
$rowFieldStringRequiredField name for row dimension (e.g., initialSeverity, severity)
$colFieldStringRequiredField name for column dimension (e.g., initialLikelihood, likelihood)
$cellCallbackMacroRequiredMacro name that calculates risk level for a given row/column combination
$colorMapMapRequiredMap of risk levels to CSS color values (e.g., low=#4CAF50, medium=#FF9800, high=#ff5722, critical=#f44336)

​
Global Output Variables

VariableTypeDescription
$nxMatrixTotalIntegerTotal count of items processed
$nxMatrixCellsMapMap of [rowVal-colVal] → count pairs for each matrix cell
$nxMatrixRiskDistributionMapMap of risk level (low/medium/high/critical) → count of items at that level
$nxMatrixRowTotalsMapMap of row value → count of items in that row
$nxMatrixColTotalsMapMap of column value → count of items in that column

​
Usage Pattern

The nxRiskMatrix macro implements a generic 2D risk matrix renderer. The page template must:
  1. Define an array of row dimension values
  2. Define an array of column dimension values
  3. Query the collection of work items to analyze
  4. Define a #calculateRisk() macro that maps a (rowVal, colVal) pair to a risk level
  5. Define a color map
  6. Call #nxRiskMatrix() with all parameters

​
Example: HAZID Risk Matrix (Initial Risk)

## Define dimensions
#set( $severityLevels = ["S1", "S2", "S3", "S4"] )
#set( $likelihoodLevels = ["L1", "L2", "L3", "L4", "L5"] )

## Query hazards
#set( $hazards = $page.workItems.query("type:hazard") )

## Define risk calculation function (implements severity × likelihood matrix)
#macro( calculateRisk $sev $like )
  #if( ($sev == "S1" && ($like == "L1" || $like == "L2" || $like == "L3" || $like == "L4")) ||
       ($sev == "S2" && ($like == "L1" || $like == "L2")) )
    #set( $riskResult = "low" )
  #elseif( ($sev == "S1" && $like == "L5") ||
           ($sev == "S2" && ($like == "L3" || $like == "L4")) ||
           ($sev == "S3" && ($like == "L1" || $like == "L2")) )
    #set( $riskResult = "medium" )
  #elseif( ($sev == "S2" && $like == "L5") ||
           ($sev == "S3" && ($like == "L3" || $like == "L4")) ||
           ($sev == "S4" && ($like == "L1" || $like == "L2")) )
    #set( $riskResult = "high" )
  #else
    #set( $riskResult = "critical" )
  #endif
#end

## Define color scheme
#set( $colorMap = {
  "low": "#4CAF50",
  "medium": "#FF9800",
  "high": "#ff5722",
  "critical": "#f44336"
} )

## Render matrix
#nxRiskMatrix( $severityLevels, $likelihoodLevels, $hazards, 
              "initialSeverity", "initialLikelihood", 
              "calculateRisk", $colorMap )

## Display summary
<p>Total Hazards Analyzed: $nxMatrixTotal</p>
<p>Low Risk: $nxMatrixRiskDistribution.low | Medium Risk: $nxMatrixRiskDistribution.medium | 
   High Risk: $nxMatrixRiskDistribution.high | Critical Risk: $nxMatrixRiskDistribution.critical</p>

​
Matrix Rendering Features

​
Cell Color Coding

Each cell in the matrix is colored based on the calculated risk level returned by the $cellCallback macro. The color is applied as a background CSS property: 
background-color: <value from $colorMap[riskLevel]>;
color: white;
font-weight: bold;

​
Cell Content

Each cell displays:
  • Count: Number of items (work items) in that cell
  • Hover Tooltip: Shows the exact row/column combination (e.g., “S2 × L3”) and count

​
Row and Column Headers

ElementContentPurpose
Row HeaderRow dimension value (e.g., S1, S2, S3, S4)Identifies severity/first dimension
Column HeaderColumn dimension value (e.g., L1, L2, L3, L4, L5)Identifies likelihood/second dimension
Row TotalSum of counts across all columns for that rowQuick row-level aggregation
Column TotalSum of counts across all columns for that columnQuick column-level aggregation

​
Integration with TestAuto2 Dashboards

​
HAZID Risk Matrix Report

The macro is used in the HAZID Risk Matrix Report page to visualize initial and residual risk distributions: 
## Initial Risk Matrix
#set( $initialSevCounts = $page.workItems.query("type:hazard") )
#nxRiskMatrix( ..., "initialSeverity", "initialLikelihood", ... )

## Residual Risk Matrix (post-mitigation)
#set( $residualSevCounts = $page.workItems.query("type:hazard AND residualRisk != null") )
#nxRiskMatrix( ..., "residualSeverity", "residualLikelihood", ... )
Both matrices are displayed side-by-side to demonstrate risk reduction effectiveness of implemented controls.

​
HARA Risk Analysis

The macro supports the ISO 26262-3 ASIL Determination Matrix (Severity × Exposure × Controllability): 
## 3D matrix display: iterate through controllability levels C1-C3
#foreach( $cc in ["C1", "C2", "C3"] )
  <h4>Controllability: $cc</h4>
  #nxRiskMatrix( $severityLevels, $exposureLevels, ..., 
                "initialSeverity", "initialExposure", ... )
#end
This produces separate matrices for each controllability level, collectively representing the full ISO 26262-3 Table 4 ASIL lookup.

​
ISO 26262 Severity × Likelihood Mapping

The following table documents the standard risk matrix algorithm used in TestAuto2 HAZID analysis: 
     L1      L2      L3      L4      L5
S1   Low     Low     Low     Low    Med
S2   Low     Low    Med     Med    High
S3   Low    Med     Med    High    Crit
S4   Med    High    High    Crit    Crit
This mapping follows typical automotive safety risk assessment practice where:
  • S1 = Minor injury
  • S2 = Serious injury
  • S3 = Life-threatening injury
  • S4 = Fatal injury
And likelihood ranges from:
  • L1 = Incredible (< 1 in 100,000 operational hours)
  • L5 = > 50% of operating time
Compare initial vs. residual risk matrices to verify that implemented risk controls are effective. A well-executed FMEA should show a clear shift of cells from High/Critical (red) to Medium/Low (green) in the residual matrix.
The macro will display empty cells for hazards missing either severity or likelihood values. Ensure all hazards are fully classified before generating reports:
  • Run query: type:hazard AND (initialSeverity IS NULL OR initialLikelihood IS NULL)
  • Complete missing assessments in HAZID risksheet

​
Color Scheme Reference

Risk LevelColorHex CodeSemantic Meaning
LowGreen#4CAF50Acceptable risk; normal controls sufficient
MediumOrange#FF9800Elevated risk; mitigation recommended; verify with FMEA
HighRed-Orange#ff5722High risk; mitigation required before production
CriticalDark Red#f44336Unacceptable risk; must implement safety controls per ISO 26262
These colors align with traffic-light risk visualization conventions used across TestAuto2 dashboards and reports.

​
Velocity Scope Considerations

The nxRiskMatrix macro modifies global Velocity variables (nxMatrixTotal,nxMatrixTotal, nxMatrixCells, etc.) to track matrix state. This differs from macros that only return values due to Velocity’s local scope constraints with #set statements.Do not rely on local variables after calling nxRiskMatrix — always reference the global $nxMatrix* outputs.

​
Common Usage Patterns

​
Pattern 1: Display Dual Matrices (Initial + Residual Risk)

<h2>Risk Assessment Summary</h2>

<h3>Initial Risk Distribution (Before Mitigation)</h3>
#nxRiskMatrix( $sev, $like, $hazards, 
              "initialSeverity", "initialLikelihood", "calcRisk", $colors )
<p>Initial Risk Distribution:</p>
<ul>
  <li>Low: $nxMatrixRiskDistribution.low</li>
  <li>Medium: $nxMatrixRiskDistribution.medium</li>
  <li>High: $nxMatrixRiskDistribution.high</li>
  <li>Critical: $nxMatrixRiskDistribution.critical</li>
</ul>

<h3>Residual Risk Distribution (After Mitigation)</h3>
#set( $residualHazards = $page.workItems.query("type:hazard AND residualRisk != null") )
#nxRiskMatrix( $sev, $like, $residualHazards, 
              "residualSeverity", "residualLikelihood", "calcRisk", $colors )
<p>Residual Risk Distribution:</p>
<ul>
  <li>Low: $nxMatrixRiskDistribution.low</li>
  <li>Medium: $nxMatrixRiskDistribution.medium</li>
  <li>High: $nxMatrixRiskDistribution.high</li>
  <li>Critical: $nxMatrixRiskDistribution.critical</li>
</ul>

​
Pattern 2: Drill-Down with Summary Cards

#nxRiskMatrix( $sev, $like, $hazards, ... )

#nxKpiCard( $nxMatrixRiskDistribution.critical, "Critical Risk", "Requires immediate action", "#f44336" )
#nxKpiCard( $nxMatrixRiskDistribution.high, "High Risk", "Mitigation in progress", "#ff5722" )
#nxKpiCard( $nxMatrixRiskDistribution.medium, "Medium Risk", "Monitor and assess", "#FF9800" )
#nxKpiCard( $nxMatrixRiskDistribution.low, "Low Risk", "Acceptable with controls", "#4CAF50" )

​
Pattern 3: Export Matrix Data to CSV

## Extract matrix data for reporting
#set( $csvOutput = "" )
#foreach( $row in $severityLevels )
  #foreach( $col in $likelihoodLevels )
    #set( $cellKey = "$row-$col" )
    #set( $count = $nxMatrixCells.get($cellKey) )
    #set( $csvOutput = "$csvOutput$row,$col,$count
" )
  #end
#end