DOCS UPDATE: Modernize area and iteration maps how-to guide with current configuration format (#2874)

MrHinsh · web-flow · commit 9f79e9a361af · 2025-07-03T10:45:52.000+01:00
The how-to guide for creating area and iteration maps was significantly outdated compared to the reference documentation. This update brings the guide up to date with the current configuration schema and best practices. ## Key Changes Made ### ✅ Updated Configuration Format - Migrated from deprecated `IterationMaps`/`AreaMaps` dictionary format to modern `Iterations.Mappings`/`Areas.Mappings` structured format - Added clear examples of the new Match/Replacement property structure - Maintained backward compatibility documentation while marking old format as deprecated ### ✅ Enhanced Documentation Structure - Added dedicated sections for Configuration Format, Regular Expressions, and Mapping Patterns - Reorganized content with better headings and logical flow - Added comprehensive working examples users can copy and adapt ### ✅ Added Missing Critical Content - **Important Warning**: Added prominent note that work items cannot be migrated if Area/Iteration paths don't exist on target - **Special Character Escaping**: Added detailed warnings about JSON and regex escaping requirements - **Filters Documentation**: Explained how to use Filters with glob patterns - **PrefixProjectToNodes Replacement**: Showed how to replace deprecated option with explicit mappings ### ✅ Practical Examples Added - Simple project rename with path preservation - Project rename to root only (hierarchy flattening) - Replacing deprecated PrefixProjectToNodes functionality - Using Filters to control node migration - Complete TfsNodeStructureToolOptions configuration example ### ✅ Better User Guidance - Links to regex101.com for testing regular expressions - Advice on terminating backslashes in patterns - Clear explanation of back-references in replacements - Cross-references to complete reference documentation ## Before vs After **Before**: Used outdated dictionary format with minimal explanation ```json "IterationMaps": { "OldProject\\Iteration": "NewProject\\Sprint" } ``` **After**: Uses modern structured format with comprehensive guidance ```json "Iterations": { "Mappings": [ { "Match": "^OldProject\\\\(.*)$", "Replacement": "NewProject\\$1" } ] } ``` The how-to guide now provides practical, actionable guidance that matches the current tool capabilities and configuration schema exactly as shown in the reference documentation. ![Regular Expression Example](https://github.com/nkdAgility/azure-devops-migration-tools/assets/5205575/2cf50929-7ea9-4a71-beab-dd8ff3b5b2a8) Fixes #2873. > [!WARNING] > > <details> > <summary>Firewall rules blocked me from connecting to one or more addresses</summary> > > #### I tried to connect to the following addresses, but was blocked by firewall rules: > > - `esm.ubuntu.com` > - Triggering command: `/usr/lib/apt/methods/https` (dns block) > > If you need me to access, download, or install something from one of these locations, you can either: > > - Configure [Actions setup steps](https://gh.io/copilot/actions-setup-steps) to set up my environment, which run before the firewall is enabled > - Add the appropriate URLs or hosts to my [firewall allow list](https://gh.io/copilot/firewall-config) > > </details>  --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.
diff --git a/.gitignore b/.gitignore
@@ -164,4 +164,5 @@ $RECYCLE.BIN/
 logs/
 /staging/
 /public/
+/docs/public/
 /docs/data/generated
diff --git a/docs/content/docs/how-to/creating-iteration-and-area-maps/index.md b/docs/content/docs/how-to/creating-iteration-and-area-maps/index.md
@@ -9,13 +9,40 @@ date: 2025-06-24T12:07:31Z
 ---
 As per the [documentation]({{< ref "docs/reference/tools/tfs-node-structure-tool" >}}), you need to add Iteration Maps and Area Maps that adapt the old locations to new ones that are valid in the Target.
 
+**NOTE: It is NOT possible to migrate a work item if the Area or Iteration path does not exist on the target project. This is because the work item will be created with the same Area and Iteration path as the source work item. If the path does not exist, the work item will not be created. _There is no way around this!_**
+
 Before your migration starts, it will validate that all of the Areas and Iterations from the **Source** work items revisions exist on the **Target**. Any that do not exist will be flagged in the logs, and if you have `"StopMigrationOnMissingAreaIterationNodes": true,` set, the migration will stop just after it outputs a list of the missing nodes.
 
 Our algorithm that converts the Source nodes to Target nodes processes the [mappings]({{< ref "docs/reference/tools/tfs-node-structure-tool" >}}) at that time. This means that any valid mapped nodes will never be caught by the `This path is not anchored in the source project` message, as they are already altered to be valid.
 
 > We recently updated the logging for this part of the system to more easily debug both your mappings and to see what the system is doing with the nodes and their current state. You can set `"LogLevel": "Debug"` to see the details.
 
-To add a mapping, you can follow [the documentation]({{< ref "docs/reference/tools/tfs-node-structure-tool" >}}) with this being the simplest way:
+## Configuration Format
+
+The modern configuration uses structured mappings with `Match` and `Replacement` properties, utilizing the new `Iterations.Mappings` and `Areas.Mappings` format:
+
+```json
+"Iterations": {
+  "Mappings": [
+    {
+      "Match": "WorkItemMovedFromProjectName\\\\Iteration 1",
+      "Replacement": "TargetProject\\Sprint 1"
+    }
+  ]
+},
+"Areas": {
+  "Mappings": [
+    {
+      "Match": "WorkItemMovedFromProjectName\\\\Team 2",
+      "Replacement": "TargetProject\\ProductA\\Team 2"
+    }
+  ]
+}
+```
+
+### Legacy Format Support
+
+_Note: The old `IterationMaps` and `AreaMaps` dictionary format is still supported for backward compatibility but is deprecated:_
 
 ```json
 "IterationMaps": {
@@ -26,50 +53,199 @@ To add a mapping, you can follow [the documentation]({{< ref "docs/reference/too
 }
 ```
 
-Or you can use regular expressions to match the missing area or iteration paths:
+## Using Regular Expressions
+
+You can use regular expressions to match and transform area or iteration paths. The syntax uses structured mappings with regular expression patterns:
 
 ```json
-"IterationMaps": {
-  "^OriginalProject\\\\Path1(?=\\\\Sprint 2022)": "TargetProject\\AnotherPath\\NewTeam",
-  "^OriginalProject\\\\Path1(?=\\\\Sprint 2020)": "TargetProject\\AnotherPath\\Archives\\Sprints 2020",
-  "^OriginalProject\\\\Path2": "TargetProject\\YetAnotherPath\\Path2"
+"Iterations": {
+  "Mappings": [
+    {
+      "Match": "^OriginalProject\\\\Path1(?=\\\\Sprint 2022)(.*)$",
+      "Replacement": "TargetProject\\AnotherPath\\NewTeam$1"
+    },
+    {
+      "Match": "^OriginalProject\\\\Path1(?=\\\\Sprint 2020)(.*)$",
+      "Replacement": "TargetProject\\AnotherPath\\Archives\\Sprints 2020$1"
+    },
+    {
+      "Match": "^OriginalProject\\\\Path2(.*)$",
+      "Replacement": "TargetProject\\YetAnotherPath\\Path2$1"
+    }
+  ]
 },
-"AreaMaps": {
-  "^OriginalProject\\\\(DescopeThis|DescopeThat)": "TargetProject\\Archive\\Descoped\\",
-  "^OriginalProject\\\\(?!DescopeThis|DescopeThat)": "TargetProject\\NewArea\\"
+"Areas": {
+  "Mappings": [
+    {
+      "Match": "^OriginalProject\\\\(DescopeThis|DescopeThat)(.*)$",
+      "Replacement": "TargetProject\\Archive\\Descoped\\$1$2"
+    },
+    {
+      "Match": "^OriginalProject\\\\(?!DescopeThis|DescopeThat)(.*)$",
+      "Replacement": "TargetProject\\NewArea\\$1"
+    }
+  ]
 }
 ```
 
-If you want to use the matches in the replacement, you can use the following:
+### Using Back-References in Replacements
+
+If you want to use captured groups in the replacement, you can reference them using `$` followed by the group number:
 
 ```json
-"IterationMaps": {
-  "^\\\\oldproject1(?:\\\\([^\\\\]+))?\\\\([^\\\\]+)$": "TargetProject\\Q1$2"
+"Iterations": {
+  "Mappings": [
+    {
+      "Match": "^\\\\oldproject1(?:\\\\([^\\\\]+))?\\\\([^\\\\]+)$",
+      "Replacement": "TargetProject\\Q1\\$2"
+    }
+  ]
 }
 ```
 
 If the old iteration path was `\oldproject1\Custom Reporting\Sprint 13`, this would result in a match for each Iteration node after the project node. You would then be able to reference any of the nodes using "$" and the number of the match.
 
+### Important Notes About Escaping
+
 Regular expressions are much more difficult to build and debug, so it is a good idea to use a [regular expression tester](https://regex101.com/) to check that you are matching the right things and to build them in ChatGPT.
 
-_NOTE: You need `\\` to escape a `\` in the pattern, and `\\` to escape a `\` in JSON. Therefore, on the left of the match, you need 4 `\` to represent the `\\` for the pattern and only 2 `\` in the match._
+**Special Character Escaping Warning:** Special characters in the acceptation of regular expressions _and_ JSON both need to be escaped. For the Match property, this means, for example, that a literal backslash must be escaped for the regular expression language `\\` _and_ each of these backslashes must then be escaped for the JSON encoding: `\\\\`. In the Replacement property, a literal `$` must be escaped with an additional `$` if it is followed by a number (due to the special meaning in regular expression replacement strings), while a backslash must be escaped (`\\`) due to the special meaning in JSON.
+
+**Advice:** To avoid unexpected results, always match terminating backslashes in the search pattern and replacement string: if a search pattern ends with a backslash, you should also put one in the replacement string, and if the search pattern does not include a terminating backslash, then none should be included in the replacement string.
+
+_NOTE: You need `\\` to escape a `\` in the pattern, and `\\` to escape a `\` in JSON. Therefore, in the Match property you need 4 `\` to represent the `\\` for the pattern and only 2 `\` in the Replacement property._
+
+## Some Useful Mapping Patterns
+
+### Simple Project Rename with Path Preservation
+
+```json
+"Iterations": {
+  "Mappings": [
+    {
+      "Match": "^OldProjectName([\\\\]?.*)$",
+      "Replacement": "NewProjectName$1"
+    }
+  ]
+},
+"Areas": {
+  "Mappings": [
+    {
+      "Match": "^OldProjectName([\\\\]?.*)$",
+      "Replacement": "NewProjectName$1"
+    }
+  ]
+}
+```
+
+This maps all `OldProjectName` area or iterations to a similar new node, preserving the entire path structure. If you have `ShouldCreateMissingRevisionPaths` enabled, it will create missing nodes automatically.
 
-## Some pretty cool mappings
+### Project Rename to Root Only
 
 ```json
-"^OldProjectName([\\\\]?.*)$": "NewProjectName$1"
+"Iterations": {
+  "Mappings": [
+    {
+      "Match": "^OldProjectName([\\\\]?.*)$",
+      "Replacement": "NewProjectName"
+    }
+  ]
+},
+"Areas": {
+  "Mappings": [
+    {
+      "Match": "^OldProjectName([\\\\]?.*)$",
+      "Replacement": "NewProjectName"
+    }
+  ]
+}
 ```
 
-or
+This maps all `OldProjectName` paths to just the new project name root, effectively flattening the hierarchy.
+
+### Replacing PrefixProjectToNodes
+
+The deprecated `PrefixProjectToNodes` option can be replaced with explicit mappings:
 
 ```json
-"^OldProjectName([\\\\]?.*)$": "NewProjectName"
+"Iterations": {
+  "Mappings": [
+    {
+      "Match": "^SourceServer\\\\(.*)$",
+      "Replacement": "TargetServer\\SourceServer\\$1"
+    }
+  ]
+},
+"Areas": {
+  "Mappings": [
+    {
+      "Match": "^SourceServer\\\\(.*)$",
+      "Replacement": "TargetServer\\SourceServer\\$1"
+    }
+  ]
+}
 ```
 
-The first one maps all `OldProjectName` area or iterations to a similar new node. If you have `CreateMissingNodes` enabled, it will create that. The second will just map all `OldProjectName` to the new project name root.
+This prepends the source project name to the target set of nodes, useful when the target project already has nodes and you don't want to merge them together.
+
+## Using Filters
 
-![image](https://github.com/nkdAgility/azure-devops-migration-tools/assets/5205575/2cf50929-7ea9-4a71-beab-dd8ff3b5b2a8)
+You can also use `Filters` to control which nodes are migrated before applying mappings:
 
+```json
+"Iterations": {
+  "Filters": ["*\\Sprint*"],
+  "Mappings": [
+    {
+      "Match": "^OriginalProject\\\\(.*)$",
+      "Replacement": "TargetProject\\$1"
+    }
+  ]
+},
+"Areas": {
+  "Filters": ["*\\Team 2", "Team 2\\*"],
+  "Mappings": [
+    {
+      "Match": "^OriginalProject\\\\(.*)$",
+      "Replacement": "TargetProject\\$1"
+    }
+  ]
+}
 ```
 
+Filters use glob patterns and are applied before mappings. You can exclude specific paths by prefixing with `!`.
+
+![Regular Expression Example](https://github.com/nkdAgility/azure-devops-migration-tools/assets/5205575/2cf50929-7ea9-4a71-beab-dd8ff3b5b2a8)
+
+## Complete Example Configuration
+
+Here's a complete example showing the TfsNodeStructureTool configuration with both Areas and Iterations mappings:
+
+```json
+{
+  "$type": "TfsNodeStructureToolOptions",
+  "Enabled": true,
+  "Areas": {
+    "Filters": [],
+    "Mappings": [
+      {
+        "Match": "^Skypoint Cloud$",
+        "Replacement": "MigrationTest5"
+      }
+    ]
+  },
+  "Iterations": {
+    "Filters": [],
+    "Mappings": [
+      {
+        "Match": "^Skypoint Cloud\\\\Sprint 1$",
+        "Replacement": "MigrationTest5\\Sprint 1"
+      }
+    ]
+  },
+  "ShouldCreateMissingRevisionPaths": true,
+  "ReplicateAllExistingNodes": true
+}
 ```
+
+For more detailed information and advanced configuration options, refer to the complete [TFS Node Structure Tool documentation]({{< ref "docs/reference/tools/tfs-node-structure-tool" >}}).
