Multi-level requirements hierarchy collapses during bulk import

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

We’re migrating a large requirements repository to Azure DevOps ado-2025 and hitting a major roadblock. Bulk CSV import of requirements loses the entire parent-child hierarchy structure. Our requirements have 4-5 levels of nesting (Epic > Feature > Requirement > Sub-requirement > Task), but after import everything appears as flat top-level items.

The CSV import templates we’re using include parent ID columns and the mapping looks correct. Work item hierarchy rules are configured in our process template, and manual creation of nested requirements works fine. But bulk migration through CSV import completely collapses the structure.

Here’s our CSV structure:

ID,Title,Type,ParentID
1,Auth Epic,Epic,
2,Login Feature,Feature,1
3,Password Req,Requirement,2

After import, all three items show ParentID as empty and exist as independent work items. This is blocking our entire migration project - we have over 3000 requirements to migrate with complex hierarchies. Has anyone successfully preserved multi-level work item hierarchies during bulk CSV imports?

2

We faced this exact challenge during our migration last year. The problem is that CSV import doesn’t support temporary ID resolution for parent references within the same import batch. Each row is processed independently, so when row 3 references ParentID=2, that ID doesn’t exist yet in the system. The import silently fails the parent assignment and creates the item as top-level. You need to import in multiple passes, creating each hierarchy level separately and using the actual generated IDs for subsequent levels.

3

Check if your ParentID column is using the correct reference format. In ado-2025, parent references in CSV imports need to use either existing work item IDs (for already created items) or temporary reference IDs (for items in the same import batch). If you’re mixing both reference types, the import process can’t resolve the hierarchy and defaults to creating flat structures. Your CSV should use consistent reference formatting throughout.

4

I’ve done several large-scale migrations to Azure DevOps. The CSV import template has limitations with parent ID mapping when dealing with more than 3 hierarchy levels. The import process doesn’t maintain a reference map of created work item IDs during the import, so deep hierarchies lose their relationships. You might need to use the REST API for bulk migration instead of CSV import to handle complex hierarchies properly.

5

I’ve successfully migrated complex requirements hierarchies to ado-2025 multiple times. Let me walk you through the complete solution:

CSV Import Templates Limitation: The standard CSV import in Azure DevOps doesn’t support forward-reference resolution for parent IDs within the same import batch. When you import a CSV with ParentID references to items that don’t exist yet, the import process can’t create the hierarchy because it processes rows sequentially without maintaining an ID mapping table.

Work Item Hierarchy Validation: Ado-2025 enforces strict hierarchy rules during import. Your Epic->Feature->Requirement->Sub-requirement->Task chain needs explicit permission in the process template. Many default templates only allow 3 levels (Epic->Feature->User Story), so deeper hierarchies get rejected and flattened.

Parent ID Mapping Strategy: For successful bulk migration, you need a two-phase approach:

Phase 1 - Process Template Configuration: First, update your process template to allow all hierarchy levels:

<WorkItemTypes>
  <WorkItemType name="Sub-requirement">
    <AllowedParents>
      <Parent ref="Requirement" />
    </AllowedParents>
  </WorkItemType>
</WorkItemTypes>

Phase 2 - Staged Import Approach: Instead of single CSV import, break your migration into hierarchy levels:

  1. Import Level 1 (Epics): Import all Epic-level items first with no parent references
Title,Type
Auth Epic,Epic
Data Epic,Epic

  1. Capture Generated IDs: After import, export the created epics to get their Azure DevOps work item IDs

  2. Import Level 2 (Features): Import features with actual parent IDs from step 2

Title,Type,ParentID
Login Feature,Feature,1001
Logout Feature,Feature,1001
  1. Repeat for each level: Continue this pattern for Requirements, Sub-requirements, and Tasks

Alternative: REST API Bulk Migration: For 3000+ requirements, CSV import is inefficient. Use the Azure DevOps REST API with batch operations:


POST https://dev.azure.com/{org}/{project}/_apis/wit/$batch
[
  {
    "method": "PATCH",
    "uri": "/_apis/wit/workitems/$Epic",
    "body": [{"op":"add","path":"/fields/System.Title","value":"Auth Epic"}]
  },
  {
    "method": "PATCH",
    "uri": "/_apis/wit/workitems/$Feature",
    "body": [
      {"op":"add","path":"/fields/System.Title","value":"Login Feature"},
      {"op":"add","path":"/relations/-","value":{
        "rel":"System.LinkTypes.Hierarchy-Reverse",
        "url":"{{Epic.url}}"
      }}
    ]
  }
]

The batch API maintains reference resolution within the batch, so parent-child relationships are preserved.

Complete Migration Solution:

  1. Validate process template allows all 5 hierarchy levels
  2. Export your source requirements data with hierarchy information
  3. Sort data by hierarchy level (depth-first or breadth-first)
  4. Use REST API batch operations (recommended) or staged CSV imports
  5. Import each hierarchy level sequentially, using generated IDs for parent references
  6. Validate hierarchy after each level import
  7. Run final validation query to verify all parent-child relationships

For your 3000 requirements, the REST API approach will complete in under an hour versus multiple days with staged CSV imports. The key is maintaining the ID mapping between your source system IDs and generated Azure DevOps IDs throughout the migration process.

6

The bulk migration issue you’re describing is a known limitation with CSV imports in Azure DevOps. The import process validates work item hierarchy rules during import, and if any parent-child relationship violates the process template rules, the entire hierarchy for that branch gets flattened. Check your process template to ensure all the work item type combinations you’re using (Epic->Feature->Requirement->Sub-requirement->Task) are explicitly allowed in the hierarchy rules. Some combinations might not be permitted by default.

7

The CSV import in ado-2025 processes work items in a single pass, which means parent items must exist before child items can reference them. If your CSV isn’t sorted so parents appear before children, the parent ID references fail silently. Try sorting your CSV by hierarchy level first, with epics at the top, then features, then requirements. This ensures parents are created before their children.