Common Dashboard Rendering Problems
Dashboard rendering failures in TestAuto2 typically manifest as:
- Blank dashboard pages — white screen with no content
- Partial rendering — header loads but statistics/widgets missing
- Velocity macro errors — error messages in place of content
- Missing statistics — count widgets show “0” or “N/A” for all metrics
- Broken document inventory — tree table fails to render
Diagnostic Decision Tree
Troubleshooting Steps
1. Verify Macro Library Import
All TestAuto2 dashboards depend on the Nextedy Solutions macro library. Check that the dashboard page includes:
#import('nextedy_solutions.vm')
#nxInit()
#nxCommonStyles()
Unknown macro: #nxSpaceBanner or Unknown macro: #nxKpiCard.
Fix: Edit the wiki page in Polarion and add the import directive at the top of the Velocity template.
Velocity macro names are case-sensitive. #nxKpiCard works, #nxKPICard or #NxKpiCard will fail. Always use exact casing from the macro library.
2. Check Lucene Query Syntax
Dashboard statistics use Lucene queries to count work items. Invalid query syntax causes “0” counts or rendering failures.
Common query errors:
- Wrong work item type:
type:systemRequirement (correct: type:sysReq)
- Invalid custom field ID:
severity:S3 (correct: haraSeverity.KEY:s3)
- Missing space filter:
type:desReq (should be: type:desReq AND moduleLocation.KEY:design)
Debugging:
- Copy the failing query from the dashboard Velocity code
- Open Work Items Tracker in Polarion
- Paste the query into the search bar
- Fix syntax errors until the query returns expected results
- Update the dashboard page with corrected query
Always test Lucene queries in the Work Items Tracker before embedding them in Velocity dashboards. This reveals syntax errors immediately without debugging Velocity code.
3. Validate Enum Field References
Dashboards that filter by ASIL, Action Priority, or severity enums must use correct enum IDs:
| Dashboard Filter | Correct Syntax | Wrong Syntax |
|---|
| ASIL D hazards | haraASIL.KEY:d | haraASIL:D |
| High Action Priority | actionPriority.KEY:ap-high | actionPriority:H |
| Severity S3 | haraSeverity.KEY:s3 | severity:S3 |
.KEY: accessor and lowercase enum IDs matching the enumeration configuration.
Verification: Check .polarion/documents/enumerations/*.xml files for exact enum option IDs.
4. Check Project Context Variable
Dashboards use $projectId to generate links and filter queries. If this variable is undefined, links break and some widgets fail.
## Should appear near top of dashboard page:
#set($projectId = $page.space.projectId)
/polarion/#/project//wiki/Documentation/... (double slash after project/).
Fix: Add the #set($projectId = ...) line before any link generation or macro calls that use $projectId.
5. Debug Velocity Macro Errors
When a Velocity macro fails, Polarion displays an error message in place of the widget:
Error rendering macro 'nxLinkCoverage':
Method 'fields' threw exception for reference $item in template
| Error Message | Cause | Fix |
|---|
Unknown macro: #nxKpiCard | Macro library not imported | Add #import('nextedy_solutions.vm') |
Method 'fields' threw exception | Work item query returned null | Add null check: #if($item)...#end |
Invalid method parameters | Wrong macro parameter count or type | Check macro signature in nextedy_solutions.vm |
Reference $variable not defined | Variable not set before use | Add #set($variable = ...) before macro call |
- Identify the failing macro from the error message
- Open
.polarion/pages/spaces/<Space>/<PageName>/page.xml in SVN
- Search for the macro call (e.g.,
#nxLinkCoverage)
- Verify parameter count and types against macro definition
- Add debug output:
{/* DEBUG: $item.id = $item.id */} to check variable values
- Fix the macro call and commit the change
6. Verify Document Inventory Tree
The #nxDocInventoryTree macro fails if:
- System Element work item type is missing or renamed
- Documents exist in spaces not included in the filter
- Module location enumeration is misconfigured
Symptom: Dashboard shows “System Element / Document” header but no rows.
Fix:
## Check parameters to nxDocInventoryTree:
#nxDocInventoryTree("requirements" "System Element / Document" true)
## ^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^
## space filter column header expandable tree
moduleLocation enum values (lowercase: requirements, design, risks, testing).
7. Check Browser JavaScript Console
Dashboard widgets may depend on client-side JavaScript for interactive features. Open browser DevTools (F12) and check the Console tab for errors:
TypeError: Cannot read property 'style' of null — DOM element not rendered by VelocityReferenceError: Driver is not defined — Missing JavaScript library importSyntaxError: Unexpected token — Velocity generated invalid JSON or JavaScript
Fix: Correct the Velocity template to output valid HTML/JavaScript. Use #escapeJavaScript() for string values embedded in <script> blocks.
8. Validate Space Color Configuration
Space dashboards use custom accent colors defined in page-level CSS. Missing color variables cause rendering glitches:
#nxCommonStyles()
<style>
:root { --nx-accent: #4527a0; } /* Design space purple */
</style>
Use consistent colors across dashboards: Requirements (#1565c0 blue), Design (#4527a0 purple), Risks (#c62828 red), Testing (#2e7d32 green), Documentation (#616161 grey).
Verification
After fixing dashboard rendering issues, verify:
- Dashboard page loads completely within 3-5 seconds
- All statistic cards show correct counts (match Work Items Tracker queries)
- Document inventory tree displays all documents organized by system element
- Traceability coverage bars render with percentage and color (red <50%, yellow 50-79%, green ≥80%)
- Report links navigate to correct wiki pages or Tracker views
- No Velocity error messages visible in page content
- Browser console shows no JavaScript errors
See Also
