AreaPaths & IterationPaths not being mapped

[jam1efrancis]

Hi,

Running version 16.0.7.

I've been able to successfully perform a test migration and almost everything is working perfectly. I think I must have a configuration issue though because I can't seem to get the tool to map the iteration or area paths. Whilst I could manually do this it would be preferable to be able to have the tool do it, as i've got quite a lot of work items to migrate.

For clarity, I'm migrating from one organisation to another, with a full access PAT specified for each. The process is changing from a custom Scrum to Agile (all default except the reflectedworkitemid field).

This is my FieldMaps section from configuration.json, names of area paths changed due to proprietary info.

      "FieldMaps": [
          {
            "FieldMapType": "RegexFieldMapConfig",
            "ApplyTo": [
              "*"
            ],
            "sourceField": "System.IterationPath",
            "targetField": "System.IterationPath",
            "pattern": "^MyApp\\\\(Sprint \\d+)$",
            "replacement": "myproject\\\\MyApp\\\\$1"
          },
          {
            "FieldMapType": "FieldValueMapConfig",
            "ApplyTo": [
              "*"
            ],
            "sourceField": "System.AreaPath",
            "targetField": "System.AreaPath",
            "valueMapping": {
              "MyApp": "myproject\\MyApp Team"
            }
          },
          {
            "FieldMapType": "FieldValueMapConfig",
            "ApplyTo": [
              "*"
            ],
            "sourceField": "System.State",
            "targetField": "System.State",
            "valueMapping": {
              "New": "New",
              "Approved": "Proposed",
              "Committed": "Active",
              "Done": "Closed",
              "Removed": "Removed",
              "*": "New"
            }
          },
          {
            "FieldMapType": "FieldValueMapConfig",
            "ApplyTo": [
              "*"
            ],
            "sourceField": "System.Reason",
            "targetField": "System.Reason",
            "valueMapping": {
              "Work Started": "Code In Progress",
              "Work Completed": "Code Completed",
              "Removed": "Removed"
            }
          }          
        ]
      }
    ]
,

When the migration runs, this is the output relating to this part of the config - it seems to be ignoring it. Have I got something wrong?

[09:19:13 DBG] [16.0.7] PopulateWorkItem:FieldUpdate: System.ChangedDate | Source:06/13/2023 14:58:58 Target:11/25/2024 09:19:13
[09:19:13 DBG] [16.0.7] PopulateWorkItem:FieldUpdate: System.AreaPath | Source:MyApp Target:myproject
[09:19:13 DBG] [16.0.7] PopulateWorkItem:FieldUpdate: System.IterationPath | Source:MyApp\Sprint 5 Target:myproject\Sprint 5

It also creates the sprints under \myproject\Iteration but it should be under myproject\MyApp\.

Note that the WorkItemTypeMappingTool IS working correctly but this is in a different section of the configuration.json file.

"CommonTools": {
      "WorkItemTypeMappingTool": {
        "Enabled": true,
        "Mappings": {
          "Product Backlog Item": "User Story",
          "Bug": "Bug",
          "Epic": "Epic",
          "Feature": "Feature",
          "Task": "Task",
          "Spike": "Issue",
          "Learning": "Issue",
          "Category": "Feature"
        }
      }
    }

TfsWorkItemMigrationProcessor settings - I've limited the scope to a few work items for testing purposes. I would appreciate any advice about the NodeBasePaths property as I think this may be causing some issues. It's hard to find an answer about what I put there, but it seems to match my source environment.

        "ProcessorType": "TfsWorkItemMigrationProcessor",
        "Enabled": true,
        "UpdateCreatedDate": true,
        "UpdateCreatedBy": true,
        "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] NOT IN ('Test Case', 'Test Suite', 'Test Plan') AND [System.Id] IN (947,920,939,904,898,222,217,216,209,103,106,107) ORDER BY [System.ChangedDate] DESC",
        "FixHtmlAttachmentLinks": true,
        "WorkItemCreateRetryLimit": 5,
        "FilterWorkItemsThatAlreadyExistInTarget": true,
        "GenerateMigrationComment": true,
        "SourceName": "WorkItemSource",
        "TargetName": "WorkItemTarget",
        "NodeBasePaths": [
          "MyApp"
        ],

Thanks in advance, let me know if I need to provide any more info but this is basically my entire config other than setting the source/target Azure DevOps locations.

[MrHinsh]

1. All Iteration and Area paths are migrated by default. They are converted from [sourceProject]\whatevers to [targetProject]\whatevers . Check How-To: Creating area and iteration maps
   for setting up mappings for other non-standard Iteration and Area Paths

2. There is no NodeBasePaths field on TfsWorkItemMigrationProcessor check the documentation for TfsNodeStructureTool

[jam1efrancis]

Thanks for responding!

Some of the links at How-to: Creating area and iteration maps do not work. I get a 404 for both of these links:

https://nkdagility.com/learn/azure-devops-migration-tools/Reference/v1/Processors/WorkItemMigrationContext/
https://nkdagility.com/learn/azure-devops-migration-tools/Reference/v1/Processors/WorkItemMigrationContext/#iteration-maps-and-area-maps

Based on the documentation I was able to find, and some more trial and error, I've now got a CommonEnrichersConfig section and "UseCommonNodeStructureEnricherConfig": true on each processor. I've updated what I can based on the documentation you linked plus what I found by poking around the website and git repo.

Unfortunately, it still seems to be ignoring path, area and state mappings. The configuration is ok in terms of syntax, but something must still be wrong as the tool is ignoring those parts. Is my regex wrong?

It's quite hard to pinpoint the problem when there are no errors to rely on. The logs just state this:

[15:50:07 DBG] [16.0.7] PopulateWorkItem:FieldUpdate: System.AreaPath | Source:SourceProject Target:TargetProject
[15:50:07 DBG] [16.0.7] PopulateWorkItem:FieldUpdate: System.IterationPath | Source:SourceProject Target:TargetProject

Area path should say: Source:SourceProject Target:TargetProject\SourceProject Team
Iteration path should say: Source:SourceProject Target:TargetProject\Source Project\Sprint x

Here's my "new" config, again with sensitive information removed.

{
  "Serilog": {
    "MinimumLevel": "Verbose"
  },
  "MigrationTools": {
    "Version": "16.0",
    "Endpoints": {
      "TeamSettingsSource": {
        "EndpointType": "TfsTeamSettingsEndpoint",
        "Collection": "https://dev.azure.com/SourceOrg/",
        "Project": "SourceProject",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "x"
        },
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItem_Id"
      },
      "TeamSettingsTarget": {
        "EndpointType": "TfsTeamSettingsEndpoint",
        "Collection": "https://dev.azure.com/TargetOrg/",
        "Project": "TargetProject",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "x"
        },
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItem_Id"
      },
      "WorkItemSource": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/SourceOrg/",
        "Project": "SourceProject",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "x"
        },
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItem_Id"
      },
      "WorkItemTarget": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/TargetOrg/",
        "Project": "TargetProject",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "x"
        },
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItem_Id"
      }
    },
    "CommonEnrichersConfig": [
      {
        "$type": "TfsNodeStructureOptions",
        "PrefixProjectToNodes": false,
        "NodeBasePaths": [],
        "AreaMaps": {
          "^SourceProject$": "TargetProject\\SourceProject team"
        },
        "IterationMaps": {
          "^SourceProject\\\\Sprint (\\d+)$": "TargetProject\\SourceProject\\Sprint $1"
        },
        "ShouldCreateMissingRevisionPaths": true,
        "ReplicateAllExistingNodes": true
      }
    ],
    "Processors": [
      {
        "ProcessorType": "TfsTeamSettingsProcessorOptions",
        "Enabled": true,
        "SourceName": "TeamSettingsSource",
        "TargetName": "TeamSettingsTarget",
        "UseCommonNodeStructureEnricherConfig": true
      },
      {
        "ProcessorType": "TfsWorkItemMigrationProcessor",
        "UseCommonNodeStructureEnricherConfig": true,
        "Enabled": true,
        "SourceName": "WorkItemSource",
        "TargetName": "WorkItemTarget",
        "UpdateCreatedDate": true,
        "UpdateCreatedBy": true,
        "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] NOT IN ('Test Case', 'Test Suite', 'Test Plan') AND [System.Id] in (34,35,36,39,29,32) ORDER BY [System.ChangedDate] DESC",
        "FixHtmlAttachmentLinks": true,
        "WorkItemCreateRetryLimit": 5,
        "FilterWorkItemsThatAlreadyExistInTarget": true,
        "GenerateMigrationComment": true,
        "FieldMaps": [
          {
            "FieldMapType": "FieldValueMapConfig",
            "ApplyTo": ["*"],
            "sourceField": "System.State",
            "targetField": "System.State",
            "valueMapping": {
              "New": "New",
              "Approved": "Proposed",
              "Committed": "Active",
              "Done": "Closed",
              "Removed": "Removed",
              "*": "New"
            }
          },
          {
            "FieldMapType": "FieldValueMapConfig",
            "ApplyTo": ["*"],
            "sourceField": "System.Reason",
            "targetField": "System.Reason",
            "valueMapping": {
              "Work Started": "Code In Progress",
              "Work Completed": "Code Completed",
              "Removed": "Removed"
            }
          }
        ]
      }
    ],
    "CommonTools": {
      "WorkItemTypeMappingTool": {
        "Enabled": true,
        "Mappings": {
          "Product Backlog Item": "User Story",
          "Bug": "Bug",
          "Epic": "Epic",
          "Feature": "Feature",
          "Task": "Task",
          "Spike": "Issue",
          "Learning": "Issue",
          "Category": "Feature"
        }
      }
    }
  }
}

[jam1efrancis]

@MrHinsh Any thoughts on this? I've tried various things and not had any success, resulting in a lot of manual updates to workitems, which is a shame as it's such a good migration tool otherwise.

[MrHinsh]

@jam1efrancis there are some old sample in the body of the pages, only examples in the "Examples" section are guaranteed to work as they are generated.

• Remove CommonEnrichersConfig and all UseCommonNodeStructureEnricherConfig as they are invalid and will not do anything
• Remove the TfsTeamSettingsProcessorOptions processor as its invalid, and team settings are migrated automatically by the work item processor by default
• Add TfsNodeStructureTool to CommonTools and configure it.

Ensure that you follow the code from TfsNodeStructureTool in the "examples" section only and you can see that you CommonEnrichersConfig matches the clasic code sample that is marked as from the old config system which was replaced in v16.

You can always run your config through devopsmigrator.exe upgrade which will remove any erroneous nodes and elements that do not conform.

---

Funding for us doing work on this tool is generally through 1) customer funding, or 2) donated free time.

Sponcer a Feature | Hire us directly