Enhance validation logging and documentation for WorkItemTypeValidatorTool (#2948)

This pull request introduces improvements to the work item type
validation process and related documentation in the migration tools
project. The main focus is on enhancing logging for better traceability,
updating documentation references, and improving code clarity.

**Enhancements to Work Item Type Validation:**

* Added detailed logging to the `ValidateWorkItemTypes` method in
`TfsWorkItemMigrationProcessor.cs`, including clear start/end markers
and guidance for configuration, to improve traceability and user
guidance.
[[1]](diffhunk://#diff-b0a23408b76051c7078de3664c94b03ef26ca367ede9f084067d8722393f130eR252-R256)
[[2]](diffhunk://#diff-b0a23408b76051c7078de3664c94b03ef26ca367ede9f084067d8722393f130eR284-R285)
* Added an explicit error log message when validation of work item types
fails, making it easier to diagnose issues during migration.
* Added a summary XML comment to the `TfsWorkItemTypeValidatorTool`
class, clarifying its purpose and usage for developers.

**Documentation and Configuration Updates:**

* Added a new alias (`/TfsWorkItemTypeValidatorTool`) to the
documentation for the Work Item Type Validator Tool, improving
discoverability.
* Updated `.vscode/settings.json` to set the default .NET solution to
`MigrationTools.slnx`, streamlining development setup.

Author: MrHinsh

.github/instructions/docs.content.docs.instructions.md

@@ -0,0 +1,59 @@
+---
+applyTo: "docs/content/docs/**"
+---
+
+# Documentation Standards
+
+All documentation content **must stay in sync with the codebase**.  
+Every page must accurately reflect the associated **data files** and **schemas**.
+
+---
+
+## Front Matter
+
+Each documentation file **may include** the following properties:
+
+- **dataFile**: Path to the generated documentation data file (stored in `docs/data/classes`)  
+  Example: `reference.tools.fieldmappingtool.yaml`
+
+- **schemaFile**: Path to the JSON schema file (stored in `docs/static/schema`)  
+  Example: `schema.tools.fieldmappingtool.json`
+
+> ⚠️ Documentation pages **must not** contain options, properties, or samples that do not exist in the corresponding `dataFile`.
+
+---
+
+## Documentation Structure
+
+Documentation files should generally include these sections (in order):
+
+1. **Overview**  
+   - Subsections: *How It Works*, *Use Cases*  
+
+2. **Configuration Structure**  
+   - Subsections: *Options*, *Sample*, *Defaults*, *Basic Examples*, *Complex Examples*  
+
+3. **Common Scenarios**  
+   - A list of common scenarios with supporting samples  
+
+4. **Good Practices**  
+   - Focus on maintainability, readability, and clarity  
+
+5. **Troubleshooting**  
+   - Common issues and their resolutions  
+
+6. **Schema**  
+   - Use the `{{< class-schema >}}` shortcode to render the schema from `schemaFile`  
+
+---
+
+## Rules
+
+- **Options** → use `{{< class-options >}}` to render the options table from `dataFile`.  
+- **Sample** → use `{{< class-sample sample="sample" >}}` to render the main sample from `dataFile`.  
+- **Defaults** → use `{{< class-sample sample="defaults" >}}` to render defaults from `dataFile`.  
+- **Basic Examples / Complex Examples** →  
+  - Include generated samples based on the `dataFile`.  
+  - Cross-reference the class object and its usage context.  
+
+---

.vscode/launch.json

@@ -39,6 +39,21 @@
             "type": "coreclr",
             "request": "attach",
             "processId": "${command:azureFunctions.pickProcess}"
+        },
+        {
+            "name": "Documentation Generator",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build only",
+            "program": "${workspaceFolder}/src/MigrationTools.ConsoleDataGenerator/bin/Debug/net8.0/MigrationTools.ConsoleDataGenerator.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/src/MigrationTools.ConsoleDataGenerator/bin/Debug/net8.0",
+            "console": "internalConsole",
+            "stopAtEntry": false,
+            "justMyCode": true,
+            "env": {
+                "DOTNET_ENVIRONMENT": "Development"
+            }
         }
     ]
 }

.vscode/settings.json

@@ -3,5 +3,6 @@
     "azureFunctions.projectLanguage": "C#",
     "azureFunctions.projectRuntime": "~4",
     "debug.internalConsoleOptions": "neverOpen",
-    "azureFunctions.preDeployTask": "publish (functions)"
+    "azureFunctions.preDeployTask": "publish (functions)",
+    "dotnet.defaultSolution": "MigrationTools.slnx"
 }

appsettings.json

@@ -178,6 +178,9 @@
                 "Enabled": true,
                 "Mappings": {
                 }
+            },
+            "TfsWorkItemTypeValidatorTool": {
+                "Enabled": true
             }
         },
         "CommonToolSamples": {
@@ -187,9 +190,25 @@
                     "RepoInSource": "RepoInTarget"
                 }
             },
-            "TfsValidateRequiredFieldTool": {
+            "TfsWorkItemTypeValidatorTool": {
                 "Enabled": true,
-                "Exclusions": [ "Work Request", "Opertunity", "Assumption" ]
+                "IncludeWorkItemtypes": [
+                    "Bug",
+                    "Task",
+                    "User Story",
+                    "Product Backlog Item",
+                    "Feature",
+                    "Epic",
+                    "Risk"
+                ],
+                "SourceFieldMappings": {
+                    "User Story": {
+                        "Microsoft.VSTS.Common.Prirucka": "Custom.Prirucka"
+                    }
+                },
+                "FixedTargetFields": {
+                    "User Story": ["Custom.Prirucka"]
+                }
             },
             "FieldMappingTool": {
                 "Enabled": true,

docs/content/docs/get-started/getting-started/index.md

@@ -65,6 +65,49 @@ The default [TfsWorkItemMigrationProcesor]({{< ref "docs/reference/processors/tf
 7. Adjust the [`NodeBasePaths`]({{< ref "docs/reference/processors/workitem-tracking-processor" >}}) or leave empty to migrate all nodes
 8. From your working folder run `devopsmigration execute --config .\configuration.json`
 
+### Common Issue: Work Item Type Validation Failures
+
+> **⚠️ IMPORTANT:** The migration tools include automatic validation that runs before migration starts and can cause your migration to fail if source and target systems have different work item types or fields.
+
+The [TfsWorkItemTypeValidatorTool]({{< ref "docs/reference/tools/tfsworkitemtypevalidatortool" >}}) automatically validates that:
+
+- All source work item types exist in the target system (or have mappings configured)
+- Required fields exist in target work item types
+- Field types are compatible between source and target
+- The ReflectedWorkItemId field exists in target work item types
+
+**If validation fails**, the migration will stop immediately with detailed error messages. Here's how to resolve common validation issues:
+
+**Missing Work Item Types:**
+
+```text
+Work item type 'Risk' does not exist in target system.
+```
+
+- **Solution 1:** Create the missing work item type in your target system
+- **Solution 2:** Configure a work item type mapping to map 'Risk' to an existing type like 'Issue'
+- **Solution 3:** Exclude the work item type from your migration query
+
+**Missing ReflectedWorkItemId Field:**
+
+```text
+'User Story' does not contain reflected work item ID field 'Custom.ReflectedWorkItemId'.
+```
+
+- **Solution:** Add the custom field to ALL work item types in your target project (see [ReflectedWorkItemId setup]({{< ref "docs/setup/reflected-workitem-id" >}}))
+
+**Missing Custom Fields:**
+
+```text
+Missing field 'Microsoft.VSTS.Common.CustomField' in 'User Story'.
+```
+
+- **Solution 1:** Add the missing field to the target work item type
+- **Solution 2:** Configure field mapping to map to an existing field
+- **Solution 3:** Exclude the field from validation if it's not needed
+
+For detailed troubleshooting and configuration options, see the [TfsWorkItemTypeValidatorTool documentation]({{< ref "docs/reference/tools/tfsworkitemtypevalidatortool" >}}).
+
 **Remember:** If you want a processor to run, its `Enabled` attribute must be set to `true`.
 
 Refer to the [Reference Guide]({{< ref "docs/reference" >}}) for more details.

docs/content/docs/how-to/creating-iteration-and-area-maps/index.md

@@ -7,13 +7,13 @@ discussionId: 1846
 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.
+As per the [documentation]({{< ref "docs/reference/tools/tfsnodestructuretool" >}}), 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.
+Our algorithm that converts the Source nodes to Target nodes processes the [mappings]({{< ref "docs/reference/tools/tfsnodestructuretool" >}}) 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.
 
@@ -248,4 +248,4 @@ Here's a complete example showing the TfsNodeStructureTool configuration with bo
 }
 ```
 
-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" >}}).
+For more detailed information and advanced configuration options, refer to the complete [TFS Node Structure Tool documentation]({{< ref "docs/reference/tools/tfsnodestructuretool" >}}).

docs/content/docs/reference/field-maps/_index.md

@@ -1,12 +1,12 @@
 ---
 title: Field Maps
 description: |
-  Field Maps are used to define how fields in the source system map to fields in the target system during migration. This section provides an overview of the field maps used in the Azure DevOps Migration Tools, including their configuration and usage. See [Field Mapping Tool]({{< ref "docs/reference/tools/field-mapping-tool" >}}) for more information.
+  Field Maps are used to define how fields in the source system map to fields in the target system during migration. This section provides an overview of the field maps used in the Azure DevOps Migration Tools, including their configuration and usage. See [Field Mapping Tool]({{< ref "docs/reference/tools/fieldmappingtool" >}}) for more information.
 short_title: Field Maps
 date: 2025-06-24T12:07:31Z
 discussionId: 2792
 aliases:
 - /learn/azure-devops-migration-tools/Reference/FieldMaps/
 
 ---
-These fieldmaps are usied by the [Field Mapping Tool]({{< ref "docs/reference/tools/field-mapping-tool" >}}) to map fields from the source to the target system. The field maps are defined in the `fieldMaps` section of the configuration file.`
+These fieldmaps are usied by the [Field Mapping Tool]({{< ref "docs/reference/tools/fieldmappingtool" >}}) to map fields from the source to the target system. The field maps are defined in the `fieldMaps` section of the configuration file.`