Overview
The macro computes bidirectional link coverage: it can measure forward links (source items linking to targets via a role) or backward links (source items with incoming links from targets). Coverage is expressed as a percentage and used to identify traceability gaps in automotive safety workflows.
Key Use Cases
- Verification Coverage: Measure percentage of system requirements verified by test cases (sysReq ← verifies ← testCase)
- Requirement Refinement: Track percentage of customer requirements refined into system requirements (customerReq → refines → sysReq)
- Risk Control Traceability: Validate that failure modes are linked to mitigation actions
- Safety Goal Allocation: Check that hazards are linked to derived safety goals
- Validation Coverage: Monitor percentage of requirements validated by validation test cases
Macro Signature
#set($result = $nxLinkCoverage($sourceItems, $targetType, $linkRole, $direction))
Parameters
| Name | Type | Description |
|---|
$sourceItems | Collection | Collection of work items to evaluate for link coverage (e.g., $sysReqList) |
$targetType | String | Work item type filter for target items (e.g., "testCase", "desReq", "riskControl") |
$linkRole | String | Link role name defining the relationship (e.g., "verifies", "refines", "mitigates") |
$direction | String | Link traversal direction: "forward" (source links to target), "backward" (target links to source) |
Return Value
The macro returns a map object with the following properties:
| Property | Type | Description |
|---|
covered | Integer | Count of source items that have at least one link matching the criteria |
total | Integer | Total count of source items evaluated |
coverage | Float | Coverage percentage (0–100): (covered / total) * 100 |
uncovered | Integer | Count of items without matching links: total - covered |
gapQuery | String | Lucene query string identifying items without links (for drill-down) |
Output Variables
When invoked, nxLinkCoverage also sets global Velocity variables for convenience:
| Variable | Type | Description |
|---|
$nxLinkCovered | Integer | Number of items with links |
$nxLinkTotal | Integer | Total items evaluated |
$nxLinkCoverage | Float | Coverage percentage |
$nxLinkUncovered | Integer | Number of items without links |
$nxLinkGapQuery | String | Gap query for missing links |
Common Link Roles
| Link Role | Direction | Source Type | Target Type | Purpose |
|---|
verifies | backward | testCase | sysReq / desReq | Test case verifies requirement (V-model) |
validates | backward | testCase | customerReq / userNeed | Test case validates requirement |
refines | forward | sysReq / desReq | parentType | Requirement refines higher-level requirement |
mitigates | backward | riskControl | failureMode | Risk control mitigates failure mode |
assesses | forward | failureMode | characteristic | Failure mode assesses characteristic |
allocates | forward | function | systemElement | Function allocated to system element |
Example: System Verification Coverage
Calculate what percentage of system requirements have verification test cases:
#set($sysReqList = $helper.queryWorkItems("type:sysReq"))
#set($result = $nxLinkCoverage($sysReqList, "testCase", "verifies", "backward"))
#set($percent = $result.coverage)
#set($gapQuery = $result.gapQuery)
System Verification Coverage: $percent% ($result.covered of $result.total)
Unverified: $result.uncovered items
[View Gap] ← query: $gapQuery
Example: Requirement Refinement Coverage
Track percentage of customer requirements decomposed into system requirements:
#set($custReqList = $helper.queryWorkItems("type:customerRequirement"))
#set($result = $nxLinkCoverage($custReqList, "sysReq", "refines", "backward"))
Customer Requirements Refined: $result.coverage% ($result.covered / $result.total)
Example: Risk Control Mitigation Coverage
Validate that all failure modes have linked risk controls:
#set($fmList = $helper.queryWorkItems("type:failureMode"))
#set($result = $nxLinkCoverage($fmList, "riskControl", "mitigates", "backward"))
#if($result.coverage < 100)
⚠️ $result.uncovered failure modes without risk controls
Gap query: $result.gapQuery
#end
Directional Link Semantics
Forward Direction
When direction="forward", the macro evaluates:
Example: Customer Requirement → refines → System Requirement
- For each customerReq in the source collection
- Check if it has outgoing links with role
"refines"
- Count how many have at least one such link to a sysReq
Backward Direction
When direction="backward", the macro evaluates:
Example: System Requirement ← verifies ← Test Case
- For each sysReq in the source collection
- Check if it has incoming links with role
"verifies"
- Count how many have at least one such link from a testCase
Coverage Interpretation
| Coverage % | Interpretation | Action |
|---|
| 100% | All items linked | ✅ No gaps |
| 90–99% | Most items linked | ⚠️ Investigate remaining gaps |
| 50–89% | Partial coverage | 🔴 Significant traceability work needed |
| <50% | Majority unlinked | 🔴 Incomplete traceability chain |
Gap Query Structure
The gapQuery property contains a Lucene query identifying items without matching links. Typical structure:
type:sysReq AND NOT backlinkedWorkItems:verifies=TA*
- Create a saved collection in Polarion (filtered view of gap items)
- Navigate to gap items for manual linking
- Pass to report generators for gap analysis
- Set as a drill-down link in dashboard widgets
Query Components
| Component | Meaning |
|---|
type:sysReq | Filter to source work item type |
NOT backlinkedWorkItems:verifies=TA* | Exclude items with backward verifies links from project prefix TA* |
NOT linkedWorkItems:refines=TA* | Exclude items with forward refines links to project TA* |
Integration with Coverage Bars
nxLinkCoverage output is typically rendered using the nxCoverageBar macro:
#set($result = $nxLinkCoverage($sysReqList, "testCase", "verifies", "backward"))
#nxCoverageBar($result.covered, $result.total, "System Verification", $result.gapQuery)
- Coverage percentage display
- Color-coded status (green ≥90%, yellow 50–89%, red <50%)
- Clickable gap link for drill-down
- Collection Size: Efficiently handles 100+ source items per invocation
- Link Queries: Polarion’s indexed Lucene queries optimize link traversal
- Multi-Invocation Dashboards: Safe to call multiple times per page (different roles/types)
- Batch Operations: For large-scale coverage analysis, combine with topic discovery for semantic grouping
| Macro | Purpose |
|---|
nxCoverageBar | Render coverage percentage as visual progress bar with gap drill-down |
nxOrphanDetect | Identify work items WITHOUT links to specified roles (orphan analysis) |
nxAPBuckets | Classify FMEA failure modes by Action Priority (H/M/L) distribution |
nxRiskMatrix | Render 2D risk matrix with severity vs. occurrence bucketing |
Common Errors
If $sourceItems is empty or null, coverage will show 0/0 = NaN. Always validate collection before macro invocation:#if($sourceItems.size() > 0)
#set($result = $nxLinkCoverage($sourceItems, ...))
#end
Link roles are case-sensitive and must match RTM model definition. Verify in .polarion/nextedy/models/*.yaml before use.
If using backward with a forward-only relationship (or vice versa), coverage will show 0%. Audit the RTM model documentation to confirm link role directionality.
To assess multi-hop traceability (e.g., sysReq → desReq → testCase), invoke nxLinkCoverage twice:#set($r1 = $nxLinkCoverage($sysReqList, "desReq", "refines", "backward"))
#set($r2 = $nxLinkCoverage($desReqList, "testCase", "verifies", "backward"))
Standards Compliance
nxLinkCoverage supports ISO 26262 and AIAG-VDA FMEA traceability verification:
- ISO 26262 Part 4: Verification coverage (requirements to test cases)
- ISO 26262 Part 8: Bidirectional traceability matrix validation
- AIAG-VDA FMEA: Risk control mitigation linkage completeness
- IATF 16949: Requirement decomposition chain continuity
Architecture Diagram
Version Info
- Available Since: Nextedy Solutions v1.0
- Last Updated: 2026 Q1
- Tested With: Polarion 22.2+, Nextedy Risksheet/Powersheet v3.5+
