Traceability matrix not generating coverage reports after requirements import

ALM Azure DevOps
, , , , , , , ,
1

Imported requirements show in traceability matrix but coverage calculation shows 0% for everything. We imported 200+ requirements from Excel using the Azure DevOps import tool and they all appear correctly in Boards.

When I generate the traceability matrix report, all requirements are listed but the “Test Coverage” column shows empty. The matrix-queries seem to run fine - no errors - but coverage is blank. I’ve manually linked a few test cases to requirements and those still show 0%.

The Analytics view shows:


Requirements: 247 total
Test Cases Linked: 0
Coverage: 0.0%

But when I query work item links directly, I can see the relationships exist. Is there a cache-refresh issue or something with link-types after import?

2

I’ll walk you through the complete resolution since this is a common post-import issue.

Root Cause: The Azure DevOps traceability-matrix uses specific link-types for coverage-calculation. The “Related” link type created by Excel import is not recognized for test coverage. The matrix-queries filter for “Microsoft.VSTS.Common.TestedBy-Forward” and “Microsoft.VSTS.Common.TestedBy-Reverse” relationships specifically.

Complete Solution - Four Focus Areas:

1. Matrix-Queries Configuration: First, understand how traceability matrix queries work. They use specific WIQL patterns:

SELECT [System.Id], [System.Title]
FROM WorkItemLinks
WHERE Source.[System.WorkItemType] = 'Requirement'
AND Target.[System.WorkItemType] = 'Test Case'
AND [System.Links.LinkType] = 'Microsoft.VSTS.Common.TestedBy-Forward'

Your “Related” links don’t match this filter, hence zero coverage.

2. Coverage-Calculation Logic: Azure DevOps calculates coverage as:

  • Total requirements with “Tested By” links / Total requirements = Coverage %
  • Each test case linked adds to coverage numerator
  • Only specific link-types count (not “Related”)

The Analytics view updates this calculation every 4-6 hours after work item changes, but only for recognized link-types.

3. Cache-Refresh Process: While Analytics has scheduled refresh, you can trigger recalculation:

  • Navigate to Project Settings → Analytics → Refresh Analytics Data
  • This forces a full rebuild (takes 30-60 minutes for large projects)
  • Only helps AFTER you fix the link-types

4. Link-Types Conversion: Converting “Related” to “Tests” links requires careful API usage:

Manual Approach (Small Scale):

  • Open requirement work item
  • Remove existing “Related” link to test case
  • Add new link, select “Tests” relationship
  • Save work item

Automated Approach (Bulk Conversion):

# Pseudocode - Link type conversion:
1. Query all requirements with "Related" links to test cases
2. For each requirement:
   a. Get current work item with relations
   b. Identify "Related" links to test case work items
   c. Remove "Related" link using PATCH API
   d. Add "Tests" link with same target work item
   e. Save changes
3. Wait 30 minutes for Analytics refresh
4. Verify coverage in traceability matrix

Detailed API Pattern:

PATCH https://dev.azure.com/{org}/{project}/_apis/wit/workitems/{reqId}
[
  {"op":"remove","path":"/relations/{index}"},
  {"op":"add","path":"/relations/-",
   "value":{
     "rel":"Microsoft.VSTS.Common.TestedBy-Forward",
     "url":"https://dev.azure.com/{org}/_apis/wit/workitems/{testCaseId}"
   }}
]

Prevention for Future Imports: When using Excel import tool:

  • Include “Link Type” column in your Excel file
  • Set value to “Tests” (not “Related”) for test case relationships
  • Use “Child” for hierarchical requirements
  • Validate link types in first 5 items before bulk import

Traceability Matrix Verification: After link conversion:

  1. Immediate Check: Query work items directly

    
SELECT * FROM WorkItemLinks WHERE [System.Links.LinkType] = 'Microsoft.VSTS.Common.TestedBy-Forward'

  2. Analytics Check (wait 1 hour): View coverage in Test Plans → Progress Report

  3. Matrix Report Check (wait 2 hours): Generate full traceability matrix

Common Pitfalls:

  • Don’t delete and recreate work items - this breaks history
  • Don’t use “Parent/Child” for test relationships - use “Tests”
  • Remember link direction matters: Requirement → Tests → Test Case
  • Bulk updates can timeout - batch in groups of 50

Coverage Calculation Timeline:

  • Link changes: Immediate in work item
  • Analytics view: 30-60 minutes
  • Traceability matrix: 1-2 hours
  • Trend reports: Next scheduled refresh (usually overnight)

Alternative: Query-Based Reporting: If you need immediate coverage data while Analytics refreshes:

SELECT [System.Id], [System.Title],
  (SELECT COUNT(*) FROM WorkItemLinks
   WHERE Source.[System.Id] = [System.Id]
   AND [System.Links.LinkType] = 'Microsoft.VSTS.Common.TestedBy-Forward') AS TestCount
FROM WorkItems
WHERE [System.WorkItemType] = 'Requirement'

This gives real-time coverage counts without waiting for Analytics cache-refresh.

Final Recommendation: For your 200+ requirements, I recommend:

  1. Convert links using PowerShell script (2-3 hours to write and test)
  2. Run conversion in batches of 50 requirements
  3. Force Analytics refresh after completion
  4. Verify coverage in traceability matrix next day
  5. Document link-types in your import template for future use

This approach has successfully restored coverage reporting for multiple teams after Excel imports.

3

Analytics data can lag behind real-time work item updates by several hours. After bulk imports, I usually wait 24 hours before checking coverage reports. The cache-refresh happens on a schedule, not immediately.

4

It’s been 3 days now since the import and manual linking. Still showing zero coverage. Is there a way to force Analytics to refresh? Or could the import process have created the wrong link-types?