diff --git a/.github/instructions/docs.content.docs.list.instructions.md b/.github/instructions/docs.content.docs.list.instructions.md new file mode 100644 index 000000000..ea704ad49 --- /dev/null +++ b/.github/instructions/docs.content.docs.list.instructions.md @@ -0,0 +1,42 @@ +--- +applyTo: "docs/content/docs/**/_index.md" +--- + +# Documentation Standards + +All documentation content **must stay in sync with the codebase**. +List pages automatically show the `description` from the front matter, followed by cards for each sub-page. This layout is applied automatically. + +--- + +## Front Matter + +- Only edit the `description`. +- The `description` must be **SEO/GEO friendly**: + - Use clear, relevant keywords. + - Keep it concise, about 150–160 characters. + - Write for humans first. + +--- + +## Content + +The content appears **after the list of sub-pages**. +It must describe the overall purpose of the collection or section, based on an **inspection of all current sub-pages**. + +Write **concise generalisms** that: +- Summarise common themes, capabilities, and patterns found across the sub-pages. +- Call out notable variations only when they matter to readers choosing where to go next. +- Link to one or two representative sub-pages when helpful, not an exhaustive list. + +--- + +## Rules + +- Content appears **after the auto-generated list of sub-pages**; do not add additional lists. +- Use the content to give context and orientation, not item-level documentation. +- Base statements on an actual review of all sub-pages in the section. +- Keep wording concise and consistent with the page’s keywords, and ensure the `description` aligns with the content. +- Update this content whenever sub-pages are added, removed, or materially changed. + +--- diff --git a/.github/instructions/docs.content.docs.instructions.md b/.github/instructions/docs.content.docs.single.instructions.md similarity index 86% rename from .github/instructions/docs.content.docs.instructions.md rename to .github/instructions/docs.content.docs.single.instructions.md index fc47c480e..9bcba3179 100644 --- a/.github/instructions/docs.content.docs.instructions.md +++ b/.github/instructions/docs.content.docs.single.instructions.md @@ -1,11 +1,12 @@ --- -applyTo: "docs/content/docs/**" +applyTo: "docs/content/docs/**/index.md" --- # Documentation Standards All documentation content **must stay in sync with the codebase**. -Every page must accurately reflect the associated **data files** and **schemas**. +Every page must accurately reflect the associated **data files** and **schemas**. +Existing manually added content must be preserved. Reorganise or adapt it as needed, but do not remove it. --- @@ -25,7 +26,8 @@ Each documentation file **may include** the following properties: ## Documentation Structure -Documentation files should generally include these sections (in order): +Documentation files should generally include these sections (in order). +Manually added content should be placed into the most relevant section, or reorganised if necessary. 1. **Overview** - Subsections: *How It Works*, *Use Cases* diff --git a/docs/content/docs/reference/tools/stringmanipulatortool/index.md b/docs/content/docs/reference/tools/stringmanipulatortool/index.md index 02b8298cd..360536a48 100644 --- a/docs/content/docs/reference/tools/stringmanipulatortool/index.md +++ b/docs/content/docs/reference/tools/stringmanipulatortool/index.md @@ -1,7 +1,8 @@ --- title: String Manipulator Tool -description: Used to process the String fields of a work item. This is useful for cleaning up data. It will limit fields to a max length and apply regex replacements based on what is configured. Each regex replacement is applied in order and can be enabled or disabled. +description: Processes and cleans up string fields in work items by applying regex patterns, length limitations, and text transformations. Essential for data cleanup and standardization during migration. dataFile: reference.tools.stringmanipulatortool.yaml +schemaFile: schema.tools.stringmanipulatortool.json slug: string-manipulator-tool aliases: - /docs/Reference/Tools/StringManipulatorTool @@ -12,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2643 --- -{{< class-description >}} +## Overview -## Options +The String Manipulator Tool provides powerful text processing capabilities for work item migration. It applies configurable string manipulations to all text fields in work items, enabling data cleanup, standardization, and format corrections during the migration process. -{{< class-options >}} +The tool processes string fields through a series of regex-based manipulators that can remove invalid characters, standardize formats, replace text patterns, and enforce field length limits. Each manipulation is applied in sequence and can be individually enabled or disabled. + +### How It Works + +The String Manipulator Tool operates on all string fields within work items during migration: + +1. **Field Processing**: The tool identifies all string-type fields in each work item +2. **Sequential Application**: Each configured manipulator is applied in the order defined in the configuration +3. **Regex Transformations**: Pattern-based replacements using regular expressions +4. **Length Enforcement**: Truncates fields that exceed the maximum allowed length +5. **Conditional Execution**: Each manipulator can be individually enabled or disabled + +The tool is automatically invoked by migration processors and applies transformations before work items are saved to the target system. + +### Use Cases + +Common scenarios where the String Manipulator Tool is essential: -## Samples +- **Data Cleanup**: Removing invalid Unicode characters, control characters, or formatting artifacts +- **Format Standardization**: Converting text patterns to consistent formats +- **Length Compliance**: Ensuring field values don't exceed target system limits +- **Character Encoding**: Fixing encoding issues from legacy systems +- **Pattern Replacement**: Updating URLs, paths, or references to match target environment + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -28,13 +55,161 @@ discussionId: 2643 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The String Manipulator Tool is configured with an array of manipulators, each defining a specific text transformation: + +```json +{ + "StringManipulatorTool": { + "Enabled": true, + "MaxStringLength": 1000000, + "Manipulators": [ + { + "$type": "RegexStringManipulator", + "Enabled": true, + "Description": "Remove invalid characters", + "Pattern": "[^\\x20-\\x7E\\r\\n\\t]", + "Replacement": "" + } + ] + } +} +``` + +### Complex Examples + +#### Manipulator Types + +Currently, the tool supports the following manipulator types: + +- **RegexStringManipulator**: Applies regular expression pattern matching and replacement + +#### Manipulator Properties + +Each manipulator supports these properties: + +- **$type**: Specifies the manipulator type (e.g., "RegexStringManipulator") +- **Enabled**: Boolean flag to enable/disable this specific manipulator +- **Description**: Human-readable description of what the manipulator does +- **Pattern**: Regular expression pattern to match text +- **Replacement**: Text to replace matched patterns (can be empty string for removal) + +## Common Scenarios + +### Removing Invalid Characters + +Remove non-printable characters that may cause issues in the target system: + +```json +{ + "$type": "RegexStringManipulator", + "Description": "Remove invalid characters from the end of the string", + "Enabled": true, + "Pattern": "[^( -~)\n\r\t]+", + "Replacement": "" +} +``` + +### Standardizing Line Endings + +Convert all line endings to a consistent format: + +```json +{ + "$type": "RegexStringManipulator", + "Description": "Standardize line endings to CRLF", + "Enabled": true, + "Pattern": "\r\n|\n|\r", + "Replacement": "\r\n" +} +``` + +### Cleaning HTML Content + +Remove or clean HTML tags from text fields: + +```json +{ + "$type": "RegexStringManipulator", + "Description": "Remove HTML tags", + "Enabled": true, + "Pattern": "<[^>]*>", + "Replacement": "" +} +``` + +### Fixing Encoding Issues + +Replace common encoding artifacts: + +```json +{ + "$type": "RegexStringManipulator", + "Description": "Fix common encoding issues", + "Enabled": true, + "Pattern": "’|“|â€\u009d", + "Replacement": "'" +} +``` + +## Good Practices + +### Pattern Testing + +- **Test regex patterns** thoroughly before applying to production data +- **Use regex testing tools** to validate patterns against sample data +- **Consider edge cases** and unintended matches in your patterns + +### Performance Considerations + +- **Order manipulators efficiently**: Place simpler patterns before complex ones +- **Use specific patterns**: Avoid overly broad regex that may match unintended content +- **Consider field length**: Set appropriate `MaxStringLength` to prevent excessive processing + +### Data Safety + +- **Backup source data**: Always maintain backups before applying string manipulations +- **Test with sample data**: Validate manipulations on a subset before full migration +- **Review results**: Check processed fields to ensure transformations are correct + +### Configuration Management + +- **Document patterns**: Include clear descriptions for each manipulator +- **Version control**: Maintain configuration files in version control +- **Incremental changes**: Test one manipulator at a time when developing complex transformations + +## Troubleshooting + +### Common Issues + +**Manipulations Not Applied:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that individual manipulators are enabled +- Review regex patterns for syntax errors +- Ensure the tool is configured in the processor's tool list + +**Unexpected Results:** + +- Test regex patterns in isolation with sample data +- Check the order of manipulators (they execute sequentially) +- Verify escape sequences in JSON configuration +- Review field content before and after processing + +**Performance Issues:** -{{< class-sample sample="classic" >}} +- Consider reducing `MaxStringLength` if processing very large fields +- Optimize regex patterns to avoid catastrophic backtracking +- Disable unnecessary manipulators +- Process smaller batches of work items -## Metadata +**Regex Pattern Errors:** -{{< class-metadata >}} +- Validate regex syntax using online tools or testing utilities +- Escape special characters properly in JSON configuration +- Consider case sensitivity requirements +- Test patterns against various input scenarios ## Schema diff --git a/docs/content/docs/reference/tools/tfsattachmenttool/index.md b/docs/content/docs/reference/tools/tfsattachmenttool/index.md index c5db4523c..46ad166dc 100644 --- a/docs/content/docs/reference/tools/tfsattachmenttool/index.md +++ b/docs/content/docs/reference/tools/tfsattachmenttool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs Attachment Tool -description: Tool for processing and migrating work item attachments between Team Foundation Server instances, handling file downloads, uploads, and attachment metadata. +title: TFS Attachment Tool +description: Manages work item attachment migration by downloading attachments from source systems, processing metadata, and uploading to target systems. Essential for preserving file attachments during migration. dataFile: reference.tools.tfsattachmenttool.yaml +schemaFile: schema.tools.tfsattachmenttool.json slug: tfs-attachment-tool aliases: - /docs/Reference/Tools/TfsAttachmentTool @@ -12,13 +13,40 @@ date: 2025-06-24T12:07:31Z discussionId: 2810 --- -{{< class-description >}} +## Overview -## Options +The TFS Attachment Tool handles the migration of work item attachments between source and target systems. It manages the complete attachment lifecycle including downloading files from the source, processing metadata, handling file storage, and uploading attachments to the target system. -{{< class-options >}} +The tool ensures that all file attachments associated with work items are properly preserved during migration, maintaining file integrity, metadata, and accessibility in the target environment. + +### How It Works + +The TFS Attachment Tool operates during work item migration to handle attachments: + +1. **Attachment Discovery**: Identifies all attachments associated with work items being migrated +2. **Download Process**: Downloads attachment files from the source system to local storage +3. **Metadata Processing**: Preserves attachment metadata including filenames, upload dates, and user information +4. **Size Validation**: Checks attachment sizes against configured limits +5. **Upload Process**: Uploads attachments to the target system and updates work item references +6. **Cleanup**: Manages temporary storage and cleanup of downloaded files + +The tool integrates seamlessly with migration processors to ensure attachments are handled transparently during work item processing. + +### Use Cases -## Samples +Common scenarios where the TFS Attachment Tool is essential: + +- **Complete Work Item Migration**: Ensuring all attachments are preserved when migrating work items +- **File Size Management**: Controlling attachment migration based on file size limits +- **Storage Optimization**: Managing local storage during the migration process +- **Incremental Migration**: Handling attachments in batched or incremental migration scenarios +- **Cross-Platform Migration**: Moving attachments between different TFS/Azure DevOps instances + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -28,13 +56,150 @@ discussionId: 2810 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Attachment Tool supports configuration for file size limits and storage management: + +```json +{ + "TfsAttachmentTool": { + "Enabled": true, + "ExportBasePath": "C:\\temp\\WorkItemAttachmentExport", + "MaxAttachmentSize": 480000000 + } +} +``` + +### Complex Examples + +#### Configuration Options + +- **Enabled**: Controls whether the attachment tool is active during migration +- **ExportBasePath**: Local directory path for temporary attachment storage during migration +- **MaxAttachmentSize**: Maximum file size (in bytes) for attachments to be migrated + +## Common Scenarios + +### Standard Attachment Migration + +Enable attachment migration with default settings: + +```json +{ + "TfsAttachmentTool": { + "Enabled": true, + "ExportBasePath": "C:\\temp\\Attachments", + "MaxAttachmentSize": 480000000 + } +} +``` + +### Large File Handling + +Configure for environments with larger attachment limits: + +```json +{ + "TfsAttachmentTool": { + "Enabled": true, + "ExportBasePath": "D:\\MigrationStorage\\Attachments", + "MaxAttachmentSize": 1073741824 + } +} +``` + +### Network Storage Configuration + +Use network storage for attachment processing: + +```json +{ + "TfsAttachmentTool": { + "Enabled": true, + "ExportBasePath": "\\\\shared-storage\\migration\\attachments", + "MaxAttachmentSize": 480000000 + } +} +``` + +### Size-Limited Migration + +Migrate only smaller attachments to manage bandwidth or storage: + +```json +{ + "TfsAttachmentTool": { + "Enabled": true, + "ExportBasePath": "C:\\temp\\Attachments", + "MaxAttachmentSize": 10485760 + } +} +``` + +## Good Practices + +### Storage Management + +- **Adequate Disk Space**: Ensure sufficient local storage for temporary attachment files +- **Fast Storage**: Use SSDs or fast storage for the export base path to improve performance +- **Network Considerations**: When using network storage, ensure reliable connectivity and adequate bandwidth + +### File Size Planning + +- **Target System Limits**: Configure MaxAttachmentSize based on target system capabilities +- **Network Bandwidth**: Consider network speed when setting size limits for remote migrations +- **Storage Costs**: Balance attachment completeness with storage and transfer costs + +### Performance Optimization + +- **Batch Processing**: Process attachments in manageable batches to optimize memory usage +- **Parallel Processing**: Leverage multiple threads for attachment download/upload operations +- **Cleanup Processes**: Regularly clean up temporary files to free storage space + +### Security Considerations + +- **File Permissions**: Ensure appropriate permissions on export base path directories +- **Temporary Storage**: Secure temporary storage location to protect sensitive attachments +- **Cleanup Procedures**: Implement proper cleanup to remove temporary files after migration + +## Troubleshooting + +### Common Issues + +**Attachments Not Migrating:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that the ExportBasePath directory exists and is writable +- Ensure sufficient disk space in the export location +- Review attachment sizes against the MaxAttachmentSize limit + +**Permission Errors:** + +- Verify write permissions on the ExportBasePath directory +- Check that the migration process has access to source attachments +- Ensure target system permissions allow attachment uploads +- Validate network path accessibility for shared storage + +**File Size Issues:** + +- Check individual attachment sizes against MaxAttachmentSize configuration +- Review target system attachment size limits +- Consider adjusting MaxAttachmentSize for specific migration requirements +- Monitor available storage space during migration + +**Performance Problems:** -{{< class-sample sample="classic" >}} +- Optimize ExportBasePath storage (use local SSDs when possible) +- Adjust batch sizes for attachment processing +- Check network bandwidth for remote storage scenarios +- Monitor system resources during attachment processing -## Metadata +**Storage Space Problems:** -{{< class-metadata >}} +- Monitor disk space in ExportBasePath during migration +- Implement cleanup procedures for processed attachments +- Consider using larger storage volumes for extensive migrations +- Use network storage for distributed migration scenarios ## Schema diff --git a/docs/content/docs/reference/tools/tfschangesetmappingtool/index.md b/docs/content/docs/reference/tools/tfschangesetmappingtool/index.md index ee444272f..0a1fbe2ed 100644 --- a/docs/content/docs/reference/tools/tfschangesetmappingtool/index.md +++ b/docs/content/docs/reference/tools/tfschangesetmappingtool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs Change Set Mapping Tool -description: Tool for creating missing area and iteration path nodes in the target project during migration. Configurable through TfsNodeStructureToolOptions to specify which node types to create. +title: TFS Changeset Mapping Tool +description: Maps source control changesets between source and target systems during work item migration, ensuring proper traceability and maintaining links between work items and code changes. dataFile: reference.tools.tfschangesetmappingtool.yaml +schemaFile: schema.tools.tfschangesetmappingtool.json slug: tfs-change-set-mapping-tool aliases: - /docs/Reference/Tools/TfsChangeSetMappingTool @@ -12,13 +13,38 @@ date: 2025-06-24T12:07:31Z discussionId: 2809 --- -{{< class-description >}} +## Overview -## Options +The TFS Changeset Mapping Tool provides functionality for mapping source control changesets between source and target systems during work item migration. This tool is essential for maintaining traceability between work items and code changes when migrating between different Team Foundation Server instances or Azure DevOps organizations. -{{< class-options >}} +The tool ensures that work item links to source control changesets are properly maintained and updated to reference the corresponding changesets in the target system. + +### How It Works + +The TFS Changeset Mapping Tool operates during work item migration to handle changeset references: + +1. **Changeset Discovery**: Identifies changeset links within work items being migrated +2. **Mapping Application**: Maps source changeset IDs to target changeset IDs +3. **Link Updates**: Updates work item changeset links to reference target system changesets +4. **Validation**: Ensures mapped changesets exist in the target system + +The tool integrates with work item migration processors to maintain proper traceability during the migration process. + +### Use Cases + +Common scenarios where the TFS Changeset Mapping Tool is essential: + +- **Source Control Migration**: When migrating both work items and source control repositories +- **Cross-System Migration**: Moving work items between different TFS/Azure DevOps instances +- **Repository Consolidation**: Combining multiple source repositories into a unified target +- **Traceability Maintenance**: Preserving code-to-work-item relationships during migration +- **Historical Preservation**: Maintaining audit trails and change history -## Samples +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -28,13 +54,96 @@ discussionId: 2809 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Changeset Mapping Tool requires minimal configuration to enable changeset mapping: + +```json +{ + "TfsChangeSetMappingTool": { + "Enabled": true + } +} +``` + +### Complex Examples + +The tool operates automatically when enabled, identifying and mapping changeset references found in work items during migration. + +## Common Scenarios + +### Standard Changeset Mapping + +Enable changeset mapping for work item migration: + +```json +{ + "TfsChangeSetMappingTool": { + "Enabled": true + } +} +``` + +### Migration with Source Control + +When migrating both work items and source control, enable the tool to maintain links: + +```json +{ + "CommonTools": { + "TfsChangeSetMappingTool": { + "Enabled": true + }, + "TfsGitRepositoryTool": { + "Enabled": true, + "Mappings": { + "SourceRepo": "TargetRepo" + } + } + } +} +``` + +## Good Practices + +### Migration Planning + +- **Source Control First**: Migrate source control repositories before work items when possible +- **Changeset Mapping**: Ensure changeset mappings are available before work item migration +- **Coordination**: Coordinate with source control migration tools for complete traceability +- **Validation**: Verify changeset existence in target before migration + +### Configuration Management + +- **Enable When Needed**: Only enable when changeset links need to be preserved +- **Integration**: Use in conjunction with source control migration tools +- **Testing**: Validate changeset mapping with sample work items +- **Documentation**: Document changeset mapping strategy and requirements + +## Troubleshooting + +### Common Issues + +**Changeset Links Not Updated:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that changesets exist in the target system +- Ensure proper changeset mapping is available +- Review migration logs for changeset-related messages + +**Missing Changesets in Target:** -{{< class-sample sample="classic" >}} +- Confirm source control migration completed successfully +- Verify changeset mapping between source and target systems +- Check permissions for accessing target changesets +- Review source control migration logs -## Metadata +**Performance Issues:** -{{< class-metadata >}} +- Changeset mapping typically doesn't impact performance significantly +- Consider migration batch sizes for large numbers of work items +- Monitor target system performance during migration +- Review overall migration strategy timing ## Schema diff --git a/docs/content/docs/reference/tools/tfsembededimagestool/index.md b/docs/content/docs/reference/tools/tfsembededimagestool/index.md index 4062a2d27..6c87ba818 100644 --- a/docs/content/docs/reference/tools/tfsembededimagestool/index.md +++ b/docs/content/docs/reference/tools/tfsembededimagestool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs Embeded Images Tool -description: Tool for creating missing area and iteration path nodes in the target project during migration. Configurable through TfsNodeStructureToolOptions to specify which node types to create. +title: TFS Embedded Images Tool +description: Processes and migrates embedded images within work item descriptions, comments, and HTML content, ensuring images are properly transferred and referenced in the target system. dataFile: reference.tools.tfsembededimagestool.yaml +schemaFile: schema.tools.tfsembededimagestool.json slug: tfs-embeded-images-tool aliases: - /docs/Reference/Tools/TfsEmbededImagesTool @@ -12,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2808 --- -{{< class-description >}} +## Overview -## Options +The TFS Embedded Images Tool handles the migration of embedded images within work item content during the migration process. This tool processes HTML content in work item descriptions, comments, and other rich text fields to identify, extract, and migrate embedded images to the target system. -{{< class-options >}} +The tool ensures that images embedded in work item content are properly preserved and accessible in the target environment, maintaining the visual context and documentation integrity of work items. + +### How It Works + +The TFS Embedded Images Tool operates during work item migration to handle embedded images: + +1. **Content Scanning**: Analyzes HTML content in work item fields for embedded image references +2. **Image Extraction**: Downloads embedded images from the source system +3. **Image Processing**: Processes images and prepares them for target system upload +4. **Reference Updates**: Updates HTML content to reference images in the target system +5. **Upload Management**: Uploads images to the target system and maintains proper linking + +The tool integrates seamlessly with work item migration processors to ensure embedded images are handled transparently. + +### Use Cases + +Common scenarios where the TFS Embedded Images Tool is essential: + +- **Rich Content Migration**: Preserving visual documentation in work item descriptions +- **Knowledge Preservation**: Maintaining screenshots, diagrams, and visual references +- **Cross-System Migration**: Moving embedded images between different TFS/Azure DevOps instances +- **Content Integrity**: Ensuring complete work item content migration including visual elements +- **Documentation Migration**: Preserving visual documentation and reference materials + +## Configuration Structure -## Samples +### Options + +{{< class-options >}} ### Sample @@ -28,13 +55,111 @@ discussionId: 2808 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Embedded Images Tool requires minimal configuration to enable image processing: + +```json +{ + "TfsEmbededImagesTool": { + "Enabled": true + } +} +``` + +### Complex Examples + +The tool operates automatically when enabled, processing all embedded images found in work item content during migration. + +## Common Scenarios + +### Standard Image Migration + +Enable embedded image processing for work item migration: + +```json +{ + "TfsEmbededImagesTool": { + "Enabled": true + } +} +``` + +### Complete Content Migration + +Use with other content migration tools for comprehensive work item migration: + +```json +{ + "CommonTools": { + "TfsEmbededImagesTool": { + "Enabled": true + }, + "TfsAttachmentTool": { + "Enabled": true, + "ExportBasePath": "C:\\temp\\Attachments" + }, + "TfsWorkItemEmbededLinkTool": { + "Enabled": true + } + } +} +``` + +## Good Practices + +### Content Management + +- **Enable for Rich Content**: Always enable when work items contain embedded images +- **Storage Planning**: Ensure adequate storage for image processing and migration +- **Network Considerations**: Plan for image download and upload bandwidth requirements +- **Content Validation**: Verify image migration with sample work items + +### Performance Optimization + +- **Batch Processing**: Process images efficiently during work item migration +- **Storage Management**: Use appropriate temporary storage for image processing +- **Network Efficiency**: Optimize image transfer based on network capabilities +- **Resource Monitoring**: Monitor system resources during image-heavy migrations + +### Quality Assurance + +- **Image Integrity**: Verify images are properly migrated and accessible +- **Reference Validation**: Ensure HTML references are correctly updated +- **Visual Testing**: Test migrated work items to confirm image display +- **Content Review**: Review migrated content for any missing or broken images + +## Troubleshooting + +### Common Issues + +**Images Not Migrating:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check source system permissions for image access +- Ensure target system allows image uploads +- Review migration logs for image-related errors + +**Broken Image References:** + +- Verify HTML content is properly processed +- Check that images were successfully uploaded to target +- Ensure image references are correctly updated +- Review target system image storage configuration + +**Performance Issues:** -{{< class-sample sample="classic" >}} +- Monitor storage space during image processing +- Consider network bandwidth for image transfers +- Review image sizes and migration batch sizes +- Optimize temporary storage location for performance -## Metadata +**Permission Errors:** -{{< class-metadata >}} +- Verify permissions to access source images +- Check target system permissions for image uploads +- Ensure proper authentication for image operations +- Review storage location permissions for temporary files ## Schema diff --git a/docs/content/docs/reference/tools/tfsgitrepositorytool/index.md b/docs/content/docs/reference/tools/tfsgitrepositorytool/index.md index b5e1ed908..532de1b08 100644 --- a/docs/content/docs/reference/tools/tfsgitrepositorytool/index.md +++ b/docs/content/docs/reference/tools/tfsgitrepositorytool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs Git Repository Tool -description: Tool for creating missing area and iteration path nodes in the target project during migration. Configurable through TfsNodeStructureToolOptions to specify which node types to create. +title: TFS Git Repository Tool +description: Maps Git repository references between source and target systems during work item migration, ensuring proper links to commits, pull requests, and repository artifacts are maintained across environments. dataFile: reference.tools.tfsgitrepositorytool.yaml +schemaFile: schema.tools.tfsgitrepositorytool.json slug: tfs-git-repository-tool aliases: - /docs/Reference/Tools/TfsGitRepositoryTool @@ -12,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2490 --- -{{< class-description >}} +## Overview -## Options +The TFS Git Repository Tool provides functionality for mapping Git repository references between source and target systems during work item migration. This tool ensures that work item links to Git commits, pull requests, and other repository artifacts are properly maintained when migrating between different Team Foundation Server instances or Azure DevOps organizations. -{{< class-options >}} +The tool handles repository name mapping and maintains traceability between work items and Git repository content across different environments. + +### How It Works + +The TFS Git Repository Tool operates during work item migration to handle Git repository references: + +1. **Repository Discovery**: Identifies Git repository references within work items being migrated +2. **Mapping Application**: Maps source repository names to target repository names +3. **Link Updates**: Updates work item links to reference target system repositories +4. **Changeset Handling**: Coordinates with changeset mapping for complete traceability +5. **Validation**: Ensures mapped repositories exist in the target system + +The tool integrates with work item migration processors to maintain proper Git repository relationships. + +### Use Cases -## Samples +Common scenarios where the TFS Git Repository Tool is essential: + +- **Git Repository Migration**: When migrating both work items and Git repositories +- **Cross-Organization Migration**: Moving work items between different Azure DevOps organizations +- **Repository Consolidation**: Combining multiple source repositories into unified targets +- **Repository Renaming**: Handling repository name changes between source and target +- **Multi-Repository Projects**: Managing complex projects with multiple Git repositories + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -28,13 +55,161 @@ discussionId: 2490 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Git Repository Tool is configured with repository mappings and changeset link options: + +```json +{ + "TfsGitRepositoryTool": { + "Enabled": true, + "Mappings": { + "SourceRepo1": "TargetRepo1", + "SourceRepo2": "TargetRepo2" + }, + "ShouldDropChangedSetLinks": false + } +} +``` + +### Complex Examples + +#### Configuration Options + +- **Enabled**: Controls whether the Git repository tool is active during migration +- **Mappings**: Dictionary mapping source repository names to target repository names +- **ShouldDropChangedSetLinks**: Whether to remove changeset links during migration + +## Common Scenarios + +### Repository Name Mapping + +Map repositories with different names between source and target: + +```json +{ + "TfsGitRepositoryTool": { + "Enabled": true, + "Mappings": { + "LegacyProjectRepo": "ModernProjectRepo", + "TeamARepo": "ConsolidatedRepo", + "TempRepo": "MainRepo" + }, + "ShouldDropChangedSetLinks": false + } +} +``` + +### Repository Consolidation + +Consolidate multiple source repositories into a single target: + +```json +{ + "TfsGitRepositoryTool": { + "Enabled": true, + "Mappings": { + "FrontEndRepo": "MonoRepo", + "BackEndRepo": "MonoRepo", + "SharedLibRepo": "MonoRepo" + }, + "ShouldDropChangedSetLinks": false + } +} +``` + +### Cross-Organization Migration + +Map repositories across different Azure DevOps organizations: + +```json +{ + "TfsGitRepositoryTool": { + "Enabled": true, + "Mappings": { + "ProjectAlpha": "MigratedProjectAlpha", + "ProjectBeta": "MigratedProjectBeta" + }, + "ShouldDropChangedSetLinks": false + } +} +``` + +### Drop Changeset Links + +Remove changeset links when repository migration is not needed: + +```json +{ + "TfsGitRepositoryTool": { + "Enabled": true, + "Mappings": {}, + "ShouldDropChangedSetLinks": true + } +} +``` + +## Good Practices + +### Repository Mapping Strategy + +- **Pre-Migration Planning**: Plan repository mappings before starting work item migration +- **Name Consistency**: Use consistent naming conventions for mapped repositories +- **Validation**: Verify target repositories exist before migration +- **Documentation**: Document repository mapping decisions and rationale + +### Migration Coordination + +- **Repository First**: Migrate Git repositories before work items when possible +- **Changeset Coordination**: Coordinate with TfsChangeSetMappingTool for complete traceability +- **Testing**: Validate repository mappings with sample work items +- **Incremental Approach**: Test repository mappings with small batches first + +### Configuration Management + +- **Mapping Files**: Maintain repository mapping configurations in version control +- **Environment Specific**: Use environment-specific mappings for different target systems +- **Change Tracking**: Document changes to repository mappings over time +- **Backup Configurations**: Maintain backups of repository mapping configurations + +## Troubleshooting + +### Common Issues + +**Repository Links Not Updated:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that repository mappings are correctly configured +- Ensure target repositories exist in the target system +- Review migration logs for repository-related messages + +**Missing Target Repositories:** + +- Confirm Git repositories were migrated to target system +- Verify repository names match the mapping configuration +- Check permissions for accessing target repositories +- Review target system repository configuration + +**Changeset Link Issues:** + +- Coordinate with TfsChangeSetMappingTool configuration +- Review ShouldDropChangedSetLinks setting +- Ensure changeset mappings are available +- Check source control migration completion + +**Mapping Configuration Errors:** -{{< class-sample sample="classic" >}} +- Validate JSON syntax in repository mappings +- Check for typos in source and target repository names +- Ensure mapping keys match source repository names exactly +- Review case sensitivity in repository names -## Metadata +**Performance Issues:** -{{< class-metadata >}} +- Repository mapping typically doesn't impact performance significantly +- Consider migration batch sizes for large numbers of work items +- Monitor target system performance during migration +- Review overall migration strategy timing ## Schema diff --git a/docs/content/docs/reference/tools/tfsnodestructuretool/index.md b/docs/content/docs/reference/tools/tfsnodestructuretool/index.md index 2e6f515c6..74541f867 100644 --- a/docs/content/docs/reference/tools/tfsnodestructuretool/index.md +++ b/docs/content/docs/reference/tools/tfsnodestructuretool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs Node Structure Tool -description: Tool for creating missing area and iteration path nodes in the target project during migration. Configurable through TfsNodeStructureToolOptions to specify which node types to create. +title: TFS Node Structure Tool +description: Migrates area path and iteration path structures between source and target systems, creating missing nodes and managing hierarchical project structures during work item migration. dataFile: reference.tools.tfsnodestructuretool.yaml +schemaFile: schema.tools.tfsnodestructuretool.json slug: tfs-node-structure-tool aliases: - /docs/Reference/Tools/TfsNodeStructureTool @@ -12,42 +13,58 @@ date: 2025-06-24T12:07:31Z discussionId: 2807 --- -{{< class-description >}} +## Overview -## Options +The TFS Node Structure Tool manages the migration of area path and iteration path structures between source and target systems. This tool is essential for ensuring that the hierarchical organization of projects is properly maintained during work item migration. -{{< class-options >}} +The tool creates missing area and iteration nodes in the target project and provides mapping capabilities to handle structural differences between source and target environments. -## Samples +### How It Works -### Sample +The TFS Node Structure Tool operates during project structure migration: -{{< class-sample sample="sample" >}} +1. **Structure Discovery**: Analyzes area and iteration path structures in the source project +2. **Node Creation**: Creates missing area and iteration nodes in the target project +3. **Hierarchy Preservation**: Maintains parent-child relationships in node structures +4. **Mapping Application**: Applies configured mappings for node path transformations +5. **Validation**: Ensures all required nodes exist before work item migration -### Defaults +The tool is typically run before work item migration to ensure target project structure compatibility. -{{< class-sample sample="defaults" >}} +### Critical Migration Requirement -### Classic +> **IMPORTANT**: It is NOT possible to migrate a work item if the Area or Iteration path does not exist in the target project. Work items are created with the same Area and Iteration paths as the source work item. If the path does not exist, the work item creation will fail. -{{< class-sample sample="classic" >}} +You have two options to solve this problem: -## Metadata +1. **Manual Creation**: Manually create the missing nodes in the target project (suitable for small numbers of missing nodes) +2. **Path Mapping**: Use `Areas.Mappings` and `Iterations.Mappings` to remap nodes to existing paths in the target project -{{< class-metadata >}} +### Use Cases -## Schema +Common scenarios where the TFS Node Structure Tool is essential: -{{< class-schema >}} +- **Project Structure Migration**: Replicating area and iteration hierarchies in target projects +- **Path Standardization**: Mapping different path structures between source and target +- **Missing Node Creation**: Automatically creating required nodes for work item migration +- **Cross-Project Migration**: Handling path differences when moving work items between projects +- **Structure Consolidation**: Combining multiple source structures into unified target hierarchies -## Iteration Maps and Area Maps +## Configuration Structure -**NOTE: It is NOT posible 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 not way around this!_** +### Options -You have two options to solve this problem: +{{< class-options >}} + +### Sample + +{{< class-sample sample="sample" >}} + +### Defaults + +{{< class-sample sample="defaults" >}} -1. You can manually create the mentioned work items. This is a good option if you have a small number of work items or a small number of missing nodes. This will not work if you have work items that were moved from one project to another. Those Nodes are impossible to create in the target project. -2. You can use the `Areas.Mappings` and `Iterations.Mappings` to remap the nodes to existing nodes in the target project. This is a good option if you have a large number of work items or a large number of missing nodes. +### Basic Examples ### Overview diff --git a/docs/content/docs/reference/tools/tfsrevisionmanagertool/index.md b/docs/content/docs/reference/tools/tfsrevisionmanagertool/index.md index 2ea09ac85..c6b9a307f 100644 --- a/docs/content/docs/reference/tools/tfsrevisionmanagertool/index.md +++ b/docs/content/docs/reference/tools/tfsrevisionmanagertool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs Revision Manager Tool -description: The TfsRevisionManagerTool manipulates the revisions of a work item to reduce the number of revisions that are migrated. +title: TFS Revision Manager Tool +description: Manages work item revision history during migration, allowing control over the number of revisions migrated and enabling revision replay for complete historical preservation. dataFile: reference.tools.tfsrevisionmanagertool.yaml +schemaFile: schema.tools.tfsrevisionmanagertool.json slug: tfs-revision-manager-tool aliases: - /docs/Reference/Tools/TfsRevisionManagerTool @@ -12,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2806 --- -{{< class-description >}} +## Overview -## Options +The TFS Revision Manager Tool provides control over work item revision history during migration. This tool allows you to manage the number of revisions that are migrated and configure whether to replay the complete revision history or migrate only the final state of work items. -{{< class-options >}} +The tool is essential for balancing migration performance with historical data preservation, allowing you to optimize migration speed while maintaining the necessary audit trail and change history. + +### How It Works + +The TFS Revision Manager Tool operates during work item migration to control revision processing: + +1. **Revision Analysis**: Analyzes the revision history of source work items +2. **Revision Limiting**: Applies maximum revision limits when configured +3. **Replay Control**: Determines whether to replay all revisions or migrate final state only +4. **Performance Optimization**: Reduces migration overhead by controlling revision volume +5. **History Preservation**: Maintains essential change history based on configuration + +The tool integrates with work item migration processors to optimize the migration process based on your requirements. + +### Use Cases -## Samples +Common scenarios where the TFS Revision Manager Tool is essential: + +- **Performance Optimization**: Reducing migration time by limiting revision history +- **Large Work Item Migration**: Managing memory and performance for work items with extensive history +- **Selective History**: Preserving only recent or important revisions +- **Audit Compliance**: Maintaining complete revision history when required +- **Migration Efficiency**: Balancing historical data with migration speed + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -28,13 +55,140 @@ discussionId: 2806 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Revision Manager Tool provides configuration options for revision control: + +```json +{ + "TfsRevisionManagerTool": { + "Enabled": true, + "ReplayRevisions": true, + "MaxRevisions": 100 + } +} +``` + +### Complex Examples + +#### Configuration Options + +- **Enabled**: Controls whether revision management is active during migration +- **ReplayRevisions**: Whether to replay all revisions or migrate only final state +- **MaxRevisions**: Maximum number of revisions to migrate per work item + +## Common Scenarios + +### Complete History Migration + +Migrate all revisions while maintaining performance limits: + +```json +{ + "TfsRevisionManagerTool": { + "Enabled": true, + "ReplayRevisions": true, + "MaxRevisions": 500 + } +} +``` + +### Limited History Migration + +Migrate only recent revisions to optimize performance: + +```json +{ + "TfsRevisionManagerTool": { + "Enabled": true, + "ReplayRevisions": true, + "MaxRevisions": 50 + } +} +``` + +### Final State Only + +Migrate only the final state of work items for maximum performance: + +```json +{ + "TfsRevisionManagerTool": { + "Enabled": true, + "ReplayRevisions": false, + "MaxRevisions": 1 + } +} +``` + +### Balanced Approach + +Moderate revision limit for balanced performance and history: + +```json +{ + "TfsRevisionManagerTool": { + "Enabled": true, + "ReplayRevisions": true, + "MaxRevisions": 100 + } +} +``` + +## Good Practices + +### Revision Strategy + +- **Assess Requirements**: Determine how much revision history is actually needed +- **Performance Testing**: Test migration performance with different revision limits +- **Stakeholder Alignment**: Align revision strategy with business requirements +- **Audit Compliance**: Consider compliance requirements for change history + +### Performance Optimization + +- **Start Conservative**: Begin with lower revision limits and increase if needed +- **Monitor Resources**: Watch memory and performance during migration +- **Batch Testing**: Test revision settings with small batches first +- **Target System Limits**: Consider target system performance with large revision counts + +### Configuration Management + +- **Environment Specific**: Use different revision limits for different environments +- **Documentation**: Document revision management decisions and rationale +- **Testing Strategy**: Test different revision scenarios before full migration +- **Backup Strategy**: Ensure source data is backed up before applying revision limits + +## Troubleshooting + +### Common Issues + +**Performance Problems:** + +- Reduce MaxRevisions to improve migration speed +- Consider setting ReplayRevisions to false for performance-critical migrations +- Monitor memory usage during migration +- Review overall migration batch sizes + +**Incomplete History:** + +- Increase MaxRevisions if more history is needed +- Ensure ReplayRevisions is set to true for complete history +- Verify revision limits meet business requirements +- Check source work item revision counts + +**Configuration Errors:** -{{< class-sample sample="classic" >}} +- Verify the tool is enabled (`"Enabled": true`) +- Check that MaxRevisions is set to a reasonable number +- Ensure ReplayRevisions setting matches requirements +- Validate configuration syntax -## Metadata +**Memory Issues:** -{{< class-metadata >}} +- Reduce MaxRevisions for work items with extensive history +- Consider migrating work items in smaller batches +- Monitor system memory during migration +- Review target system memory requirements ## Schema diff --git a/docs/content/docs/reference/tools/tfsteamsettingstool/index.md b/docs/content/docs/reference/tools/tfsteamsettingstool/index.md index 235f26e77..326bdd63c 100644 --- a/docs/content/docs/reference/tools/tfsteamsettingstool/index.md +++ b/docs/content/docs/reference/tools/tfsteamsettingstool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs Team Settings Tool -description: Tool for migrating team settings including team configurations, area paths, iterations, and team-specific settings from source to target Team Foundation Server or Azure DevOps. +title: TFS Team Settings Tool +description: Configures team settings including backlog navigation levels, iteration paths, and area paths during migration to ensure proper team configuration in the target system. dataFile: reference.tools.tfsteamsettingstool.yaml +schemaFile: schema.tools.tfsteamsettingstool.json slug: tfs-team-settings-tool aliases: - /docs/Reference/Tools/TfsTeamSettingsTool @@ -12,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2805 --- -{{< class-description >}} +## Overview -## Options +The TFS Team Settings Tool configures team-specific settings during migration, including backlog navigation levels, iteration paths, and area paths. This tool ensures that teams maintain their organizational structure and agile process configuration when migrating to a new Azure DevOps environment. -{{< class-options >}} +The tool is crucial for maintaining team productivity by preserving their configured work item hierarchies, sprint planning capabilities, and organizational boundaries. + +### How It Works + +The TFS Team Settings Tool operates during team configuration migration: + +1. **Team Discovery**: Identifies all teams in the source project +2. **Settings Analysis**: Analyzes current team settings including backlogs and paths +3. **Configuration Migration**: Migrates team-specific configurations to target system +4. **Path Mapping**: Maps area paths and iteration paths to target structure +5. **Validation**: Verifies team settings are correctly applied in target system + +The tool integrates with project structure migration to ensure teams can operate effectively in the migrated environment. + +### Use Cases + +Common scenarios where the TFS Team Settings Tool is essential: -## Samples +- **Team Organization**: Preserving team structure and responsibilities +- **Agile Process Continuity**: Maintaining sprint and backlog configurations +- **Area Path Management**: Ensuring teams have correct area path assignments +- **Iteration Planning**: Preserving iteration path configurations for sprint planning +- **Hierarchical Work Items**: Maintaining proper backlog level configurations + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -28,13 +55,186 @@ discussionId: 2805 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Team Settings Tool provides configuration options for team migration: + +```json +{ + "TfsTeamSettingsTool": { + "Enabled": true, + "MigrateTeamSettings": true, + "UpdateTeamSettings": true, + "PrefixProjectToNodes": false, + "Teams": [ + "Team A", + "Team B" + ] + } +} +``` + +### Complex Examples + +#### Full Team Settings Migration + +Complete migration of all team settings: + +```json +{ + "TfsTeamSettingsTool": { + "Enabled": true, + "MigrateTeamSettings": true, + "UpdateTeamSettings": true, + "PrefixProjectToNodes": true, + "Teams": ["Development Team", "QA Team", "DevOps Team"] + } +} +``` + +#### Selective Team Migration + +Migrate only specific teams: + +```json +{ + "TfsTeamSettingsTool": { + "Enabled": true, + "MigrateTeamSettings": true, + "UpdateTeamSettings": false, + "PrefixProjectToNodes": false, + "Teams": ["Core Development Team"] + } +} +``` + +## Common Scenarios + +### Complete Team Migration + +Migrate all team settings with full configuration: + +```json +{ + "TfsTeamSettingsTool": { + "Enabled": true, + "MigrateTeamSettings": true, + "UpdateTeamSettings": true, + "PrefixProjectToNodes": true + } +} +``` + +### Path Prefix Management + +Control whether project names are prefixed to node paths: + +```json +{ + "TfsTeamSettingsTool": { + "Enabled": true, + "MigrateTeamSettings": true, + "UpdateTeamSettings": true, + "PrefixProjectToNodes": false + } +} +``` + +### Team-Specific Migration + +Migrate settings for specific teams only: + +```json +{ + "TfsTeamSettingsTool": { + "Enabled": true, + "MigrateTeamSettings": true, + "UpdateTeamSettings": true, + "Teams": [ + "Scrum Team Alpha", + "Scrum Team Beta", + "Platform Team" + ] + } +} +``` + +### Settings Update Only + +Update existing team settings without full migration: + +```json +{ + "TfsTeamSettingsTool": { + "Enabled": true, + "MigrateTeamSettings": false, + "UpdateTeamSettings": true, + "Teams": ["Development Team"] + } +} +``` + +## Good Practices + +### Team Configuration + +- **Document Structure**: Document current team organization before migration +- **Validate Paths**: Ensure area and iteration paths exist in target before migration +- **Team Alignment**: Coordinate with team leads about configuration changes +- **Testing**: Test team settings migration with a small subset first + +### Path Management + +- **Consistent Naming**: Use consistent naming conventions for area and iteration paths +- **Hierarchy Planning**: Plan the team hierarchy structure for the target system +- **Permission Alignment**: Ensure team permissions align with area path assignments +- **Sprint Configuration**: Verify iteration paths support team sprint planning needs + +### Migration Strategy + +- **Incremental Approach**: Migrate teams incrementally to identify issues early +- **Validation Process**: Establish validation process for team settings +- **Rollback Plan**: Have rollback procedures for team configuration issues +- **Communication**: Communicate changes to affected teams + +## Troubleshooting + +### Common Issues + +**Team Settings Not Applied:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that `MigrateTeamSettings` is set to true +- Ensure target project exists and is accessible +- Verify team names in configuration match source teams + +**Path Configuration Problems:** + +- Verify area paths exist in target project structure +- Check iteration path configuration in target system +- Ensure `PrefixProjectToNodes` setting matches target structure +- Validate path permissions for teams + +**Selective Team Issues:** + +- Check team names in `Teams` array match exactly +- Verify teams exist in source system +- Ensure team names don't contain special characters +- Check for case sensitivity in team names + +**Update Problems:** -{{< class-sample sample="classic" >}} +- Verify `UpdateTeamSettings` is configured correctly +- Check permissions for updating team settings +- Ensure target teams exist before updating settings +- Validate team configuration dependencies -## Metadata +### Performance Considerations -{{< class-metadata >}} +- **Large Team Counts**: Consider batch processing for organizations with many teams +- **Complex Hierarchies**: Monitor performance with complex area/iteration structures +- **Permission Dependencies**: Account for permission inheritance in path structures +- **Validation Time**: Allow extra time for team settings validation ## Schema diff --git a/docs/content/docs/reference/tools/tfsusermappingtool/index.md b/docs/content/docs/reference/tools/tfsusermappingtool/index.md index bb8242c26..b32e8bcc9 100644 --- a/docs/content/docs/reference/tools/tfsusermappingtool/index.md +++ b/docs/content/docs/reference/tools/tfsusermappingtool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs User Mapping Tool -description: The TfsUserMappingTool is used to map users from the source to the target system. Run it with the ExportUsersForMappingContext to create a mapping file then with WorkItemMigrationContext to use the mapping file to update the users in the target system as you migrate the work items. +title: TFS User Mapping Tool +description: Maps user identities between source and target systems during work item migration, ensuring proper assignment of work items, history, and user references across different environments or organizations. dataFile: reference.tools.tfsusermappingtool.yaml +schemaFile: schema.tools.tfsusermappingtool.json slug: tfs-user-mapping-tool aliases: - /docs/Reference/Tools/TfsUserMappingTool @@ -12,13 +13,44 @@ date: 2025-06-24T12:07:31Z discussionId: 2804 --- -{{< class-description >}} +## Overview -## Options +The TFS User Mapping Tool provides essential functionality for mapping user identities between source and target systems during migration. This tool ensures that work item assignments, history records, and user references are properly maintained when migrating between different environments, organizations, or domain structures. -{{< class-options >}} +The tool supports both automatic user matching and manual mapping configuration, allowing for flexible user identity management during complex migration scenarios. + +### How It Works + +The TFS User Mapping Tool operates in two main phases during migration: + +1. **User Discovery and Export**: The tool can be used with export processors to identify and export user mappings +2. **Migration-Time Mapping**: During work item migration, the tool applies user mappings to maintain proper identity references + +The tool processes user identity fields in work items and applies configured mappings to ensure users are properly referenced in the target system. + +### Key Features + +- **Automatic Email Matching**: Attempts to match users based on email addresses +- **Manual Mapping Files**: Supports external user mapping files for complex scenarios +- **Identity Field Processing**: Handles all identity-related fields in work items +- **Validation Options**: Can validate that all users exist in the target system +- **Group Membership**: Supports mapping based on group membership validation -## Samples +### Use Cases + +Common scenarios where the TFS User Mapping Tool is essential: + +- **Cross-Domain Migration**: Moving between different Active Directory domains +- **Organization Migration**: Migrating between Azure DevOps organizations with different user bases +- **User Account Changes**: Handling scenarios where user accounts have changed between systems +- **Contractor to Employee**: Managing identity changes when contractors become employees +- **Merge Scenarios**: Consolidating users during organizational mergers + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -28,13 +60,193 @@ discussionId: 2804 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS User Mapping Tool supports several configuration options for flexible user mapping: + +```json +{ + "TfsUserMappingTool": { + "Enabled": true, + "IdentityFieldsToCheck": [ + "System.AssignedTo", + "System.CreatedBy", + "System.ChangedBy", + "Microsoft.VSTS.Common.ActivatedBy", + "Microsoft.VSTS.Common.ResolvedBy", + "Microsoft.VSTS.Common.ClosedBy" + ], + "UserMappingFile": "usermapping.json", + "MatchUsersByEmail": true, + "SkipValidateAllUsersExistOrAreMapped": false, + "ProjectCollectionValidUsersGroupName": "Project Collection Valid Users" + } +} +``` + +### Complex Examples + +#### Configuration Options + +- **IdentityFieldsToCheck**: Array of field reference names that contain user identities +- **UserMappingFile**: Path to JSON file containing manual user mappings +- **MatchUsersByEmail**: Attempt automatic matching based on email addresses +- **SkipValidateAllUsersExistOrAreMapped**: Skip validation that all users are properly mapped +- **ProjectCollectionValidUsersGroupName**: Group name for validating user membership + +## Common Scenarios + +### Automatic Email-Based Matching + +Enable automatic user matching based on email addresses: + +```json +{ + "TfsUserMappingTool": { + "Enabled": true, + "MatchUsersByEmail": true, + "SkipValidateAllUsersExistOrAreMapped": false + } +} +``` + +### Manual User Mapping File + +Use a custom mapping file for complex user scenarios: + +```json +{ + "TfsUserMappingTool": { + "Enabled": true, + "UserMappingFile": "C:\\temp\\usermapping.json", + "MatchUsersByEmail": false, + "SkipValidateAllUsersExistOrAreMapped": false + } +} +``` + +### Custom Identity Fields + +Configure specific identity fields to process: + +```json +{ + "TfsUserMappingTool": { + "Enabled": true, + "IdentityFieldsToCheck": [ + "System.AssignedTo", + "System.CreatedBy", + "System.ChangedBy", + "Custom.TeamLead", + "Custom.ProjectManager" + ], + "MatchUsersByEmail": true + } +} +``` + +### Validation Bypass + +Skip user validation for scenarios where not all users need to exist in target: + +```json +{ + "TfsUserMappingTool": { + "Enabled": true, + "MatchUsersByEmail": true, + "SkipValidateAllUsersExistOrAreMapped": true + } +} +``` + +## User Mapping File Format + +When using a manual user mapping file, the format should be a JSON array of mapping objects: + +```json +[ + { + "Source": "domain\\sourceuser", + "Target": "targetdomain\\targetuser" + }, + { + "Source": "olddomain\\john.doe", + "Target": "newdomain\\john.doe" + }, + { + "Source": "contractor@external.com", + "Target": "employee@company.com" + } +] +``` + +## Good Practices + +### User Mapping Strategy + +- **Email Matching First**: Use automatic email matching when possible to reduce manual configuration +- **Validate Mappings**: Always validate that target users exist before migration +- **Document Changes**: Maintain clear documentation of user mapping decisions +- **Test with Samples**: Validate user mappings with sample work items before full migration + +### File Management + +- **Secure Storage**: Store user mapping files securely due to sensitive identity information +- **Version Control**: Maintain user mapping files in version control for reproducibility +- **Backup Mappings**: Keep backups of user mapping configurations +- **Regular Updates**: Update mappings when user accounts change + +### Performance Considerations + +- **Efficient Lookups**: Tool performs cached lookups for optimal performance +- **Batch Processing**: User mappings are applied efficiently during work item processing +- **Identity Field Optimization**: Only configure necessary identity fields to improve performance + +### Security and Compliance + +- **Data Privacy**: Handle user identity information according to privacy policies +- **Access Control**: Restrict access to user mapping files and configurations +- **Audit Trail**: Maintain audit trails of user mapping changes +- **Compliance**: Ensure user mapping practices comply with organizational policies + +## Troubleshooting + +### Common Issues + +**Users Not Found in Target:** + +- Verify that target users exist in the target system +- Check that user accounts are active in the target environment +- Ensure proper permissions for user lookup operations +- Review group membership requirements + +**Email Matching Failures:** + +- Verify email addresses are consistent between source and target +- Check for email format differences or case sensitivity issues +- Consider using manual mapping for problematic users +- Review email address availability in both systems + +**Mapping File Issues:** + +- Validate JSON syntax in user mapping files +- Check file paths and accessibility +- Ensure proper encoding for special characters in usernames +- Verify source and target user format consistency + +**Performance Problems:** -{{< class-sample sample="classic" >}} +- Optimize the list of identity fields to check +- Use caching mechanisms for repeated user lookups +- Consider batch processing for large user sets +- Monitor system resources during user validation -## Metadata +**Validation Errors:** -{{< class-metadata >}} +- Review user existence in target system +- Check group membership requirements +- Validate user permissions for migration operations +- Consider using SkipValidateAllUsersExistOrAreMapped for specific scenarios ## Schema diff --git a/docs/content/docs/reference/tools/tfsvalidaterequiredfieldtool/index.md b/docs/content/docs/reference/tools/tfsvalidaterequiredfieldtool/index.md index daeedad67..b6df4ebca 100644 --- a/docs/content/docs/reference/tools/tfsvalidaterequiredfieldtool/index.md +++ b/docs/content/docs/reference/tools/tfsvalidaterequiredfieldtool/index.md @@ -1,7 +1,8 @@ --- -title: Tfs Validate Required Field Tool -description: Tool for validating that required fields exist in target work item types before migration, preventing migration failures due to missing required fields. +title: TFS Validate Required Field Tool +description: Validates that required fields are properly configured and populated during migration to prevent work item creation failures in the target system. dataFile: reference.tools.tfsvalidaterequiredfieldtool.yaml +schemaFile: schema.tools.tfsvalidaterequiredfieldtool.json slug: tfs-validate-required-field-tool aliases: - /docs/Reference/Tools/TfsValidateRequiredFieldTool @@ -12,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2803 --- -{{< class-description >}} +## Overview -## Options +The TFS Validate Required Field Tool validates that required fields are properly configured and populated during migration. This tool prevents work item creation failures by ensuring all mandatory fields have valid values before attempting to create work items in the target system. -{{< class-options >}} +The tool is essential for ensuring migration success by identifying and resolving field validation issues before they cause work item creation to fail. + +### How It Works + +The TFS Validate Required Field Tool operates during work item migration validation: + +1. **Field Analysis**: Analyzes target work item types to identify required fields +2. **Value Validation**: Validates that required fields have appropriate values +3. **Missing Field Detection**: Identifies work items with missing required field values +4. **Default Value Application**: Applies default values to required fields when configured +5. **Validation Reporting**: Reports validation issues for manual resolution + +The tool integrates with work item migration processors to ensure data quality before migration. + +### Use Cases + +Common scenarios where the TFS Validate Required Field Tool is essential: -## Samples +- **Migration Quality Assurance**: Ensuring all work items will migrate successfully +- **Required Field Compliance**: Meeting target system field requirements +- **Data Completeness**: Identifying incomplete work item data before migration +- **Process Template Differences**: Handling different required fields between systems +- **Migration Failure Prevention**: Avoiding work item creation failures during migration + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -28,13 +55,206 @@ discussionId: 2803 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Validate Required Field Tool provides configuration options for field validation: + +```json +{ + "TfsValidateRequiredFieldTool": { + "Enabled": true, + "ValidateRequiredFields": true, + "ApplyDefaultValues": true, + "RequiredFieldDefaultValues": { + "Microsoft.VSTS.Common.Priority": "2", + "Microsoft.VSTS.Common.Severity": "3 - Medium" + } + } +} +``` + +### Complex Examples + +#### Comprehensive Field Validation + +Complete validation with multiple default values: + +```json +{ + "TfsValidateRequiredFieldTool": { + "Enabled": true, + "ValidateRequiredFields": true, + "ApplyDefaultValues": true, + "RequiredFieldDefaultValues": { + "Microsoft.VSTS.Common.Priority": "2", + "Microsoft.VSTS.Common.Severity": "3 - Medium", + "Microsoft.VSTS.Common.Triage": "Pending", + "System.AreaPath": "DefaultProject\\General", + "System.IterationPath": "DefaultProject\\Iteration 1" + } + } +} +``` + +#### Validation Only Mode + +Validate without applying defaults for reporting purposes: + +```json +{ + "TfsValidateRequiredFieldTool": { + "Enabled": true, + "ValidateRequiredFields": true, + "ApplyDefaultValues": false, + "RequiredFieldDefaultValues": {} + } +} +``` + +## Common Scenarios + +### Complete Validation with Defaults + +Validate and apply default values for missing required fields: + +```json +{ + "TfsValidateRequiredFieldTool": { + "Enabled": true, + "ValidateRequiredFields": true, + "ApplyDefaultValues": true, + "RequiredFieldDefaultValues": { + "Microsoft.VSTS.Common.Priority": "2", + "Microsoft.VSTS.Common.Severity": "3 - Medium" + } + } +} +``` + +### Priority and Severity Defaults + +Configure defaults for common required fields: + +```json +{ + "TfsValidateRequiredFieldTool": { + "Enabled": true, + "ValidateRequiredFields": true, + "ApplyDefaultValues": true, + "RequiredFieldDefaultValues": { + "Microsoft.VSTS.Common.Priority": "3", + "Microsoft.VSTS.Common.Severity": "4 - Low", + "Microsoft.VSTS.Common.BusinessValue": "0" + } + } +} +``` + +### Path Field Validation + +Ensure area and iteration path requirements are met: + +```json +{ + "TfsValidateRequiredFieldTool": { + "Enabled": true, + "ValidateRequiredFields": true, + "ApplyDefaultValues": true, + "RequiredFieldDefaultValues": { + "System.AreaPath": "MigratedProject\\General", + "System.IterationPath": "MigratedProject\\Sprint 1" + } + } +} +``` + +### Custom Field Defaults + +Handle custom required fields with appropriate defaults: + +```json +{ + "TfsValidateRequiredFieldTool": { + "Enabled": true, + "ValidateRequiredFields": true, + "ApplyDefaultValues": true, + "RequiredFieldDefaultValues": { + "Custom.Department": "IT", + "Custom.Customer": "Internal", + "Custom.Component": "General" + } + } +} +``` + +## Good Practices + +### Field Validation Strategy + +- **Analyze Target Requirements**: Understand target system required field requirements +- **Map Field Differences**: Identify differences in required fields between systems +- **Default Value Selection**: Choose appropriate default values that make business sense +- **Testing Validation**: Test validation rules with sample work items + +### Default Value Management + +- **Business Alignment**: Ensure default values align with business processes +- **Data Quality**: Use meaningful defaults rather than placeholder values +- **Stakeholder Input**: Get stakeholder input on appropriate default values +- **Documentation**: Document default value choices and rationale + +### Configuration Management + +- **Environment Specific**: Use environment-specific default values when appropriate +- **Regular Review**: Regularly review and update default values as processes evolve +- **Validation Testing**: Test validation configuration before full migration +- **Backup Strategy**: Maintain backup of validation configurations + +## Troubleshooting + +### Common Issues + +**Validation Failures:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that `ValidateRequiredFields` is set to true +- Ensure all required fields in target system are identified +- Verify field reference names are correct + +**Default Value Problems:** + +- Check that `ApplyDefaultValues` is enabled +- Verify default values match target field value formats +- Ensure default values are valid for the field type +- Check for special characters or formatting requirements + +**Field Reference Issues:** + +- Use correct field reference names (e.g., "Microsoft.VSTS.Common.Priority") +- Verify field exists in target work item type +- Check for case sensitivity in field names +- Ensure custom fields use proper naming conventions + +**Migration Failures:** + +- Validate that all required fields have values after processing +- Check for fields that require specific value formats +- Verify area and iteration paths exist in target system +- Ensure user fields reference valid users in target system + +### Performance Considerations -{{< class-sample sample="classic" >}} +- **Large Work Item Counts**: Monitor performance with extensive work item validation +- **Complex Validation Rules**: Consider impact of complex validation logic +- **Default Value Processing**: Account for time needed to apply default values +- **Validation Reporting**: Balance validation detail with performance requirements -## Metadata +### Data Quality Validation -{{< class-metadata >}} +- **Field Value Formats**: Ensure default values match expected formats +- **Business Rule Compliance**: Verify defaults comply with business rules +- **Cross-Field Dependencies**: Consider dependencies between required fields +- **Process Template Alignment**: Align validation with target process template requirements ## Schema diff --git a/docs/content/docs/reference/tools/tfsworkitemembededlinktool/index.md b/docs/content/docs/reference/tools/tfsworkitemembededlinktool/index.md index 667ad925d..b89f6b738 100644 --- a/docs/content/docs/reference/tools/tfsworkitemembededlinktool/index.md +++ b/docs/content/docs/reference/tools/tfsworkitemembededlinktool/index.md @@ -1,6 +1,6 @@ --- -title: Tfs Work Item Embeded Link Tool -description: Tool for processing embedded links within work item fields, such as links in HTML fields and converting work item references between source and target systems. +title: TFS Work Item Embedded Link Tool +description: Processes and migrates embedded links within work item fields, ensuring that internal references and hyperlinks are correctly updated for the target system. dataFile: reference.tools.tfsworkitemembededlinktool.yaml schemaFile: schema.tools.tfsworkitemembededlinktool.json slug: tfs-work-item-embeded-link-tool @@ -13,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2802 --- -{{< class-description >}} +## Overview -## Options +The TFS Work Item Embedded Link Tool processes and migrates embedded links within work item fields. This tool ensures that internal references, hyperlinks, and embedded content within work item descriptions and other HTML fields are correctly updated to point to the target system. -{{< class-options >}} +The tool is crucial for maintaining the integrity of work item content that contains links to other work items, documents, or system resources during migration. + +### How It Works + +The TFS Work Item Embedded Link Tool operates during work item field processing: + +1. **Link Detection**: Scans work item fields for embedded links and references +2. **Link Analysis**: Analyzes link types and target destinations +3. **URL Transformation**: Updates links to point to target system locations +4. **Content Processing**: Processes HTML content to update embedded references +5. **Link Validation**: Validates that updated links are correctly formatted + +The tool integrates with work item migration processors to ensure content integrity during migration. + +### Use Cases + +Common scenarios where the TFS Work Item Embedded Link Tool is essential: -## Samples +- **Internal Link Migration**: Updating links between work items during migration +- **Documentation References**: Maintaining links to documentation and resources +- **Cross-Project Links**: Handling links that span multiple projects +- **URL Format Updates**: Converting link formats between different system versions +- **Content Integrity**: Preserving rich content with embedded links and references + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -29,13 +55,203 @@ discussionId: 2802 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Work Item Embedded Link Tool provides configuration options for link processing: + +```json +{ + "TfsWorkItemEmbeddedLinkTool": { + "Enabled": true, + "ProcessEmbeddedLinks": true, + "UpdateUrls": true, + "FilterWorkItemTypes": [], + "SourceUrlPattern": "https://source-tfs:8080/tfs/", + "TargetUrlPattern": "https://target-devops.visualstudio.com/" + } +} +``` + +### Complex Examples + +#### Complete Link Processing + +Process all embedded links with URL pattern replacement: + +```json +{ + "TfsWorkItemEmbeddedLinkTool": { + "Enabled": true, + "ProcessEmbeddedLinks": true, + "UpdateUrls": true, + "FilterWorkItemTypes": ["Bug", "User Story", "Task"], + "SourceUrlPattern": "https://old-tfs.company.com:8080/tfs/DefaultCollection/", + "TargetUrlPattern": "https://dev.azure.com/company/", + "LinkUpdatePatterns": { + "workitem": "/_workitems/edit/{id}", + "build": "/_build/results?buildId={id}", + "changeset": "/_versionControl/changeset/{id}" + } + } +} +``` + +#### Selective Processing + +Process embedded links for specific work item types only: + +```json +{ + "TfsWorkItemEmbeddedLinkTool": { + "Enabled": true, + "ProcessEmbeddedLinks": true, + "UpdateUrls": true, + "FilterWorkItemTypes": ["Epic", "Feature"], + "SourceUrlPattern": "https://tfs2018.internal/", + "TargetUrlPattern": "https://dev.azure.com/organization/" + } +} +``` + +## Common Scenarios + +### Complete URL Migration + +Update all embedded links to target system URLs: + +```json +{ + "TfsWorkItemEmbeddedLinkTool": { + "Enabled": true, + "ProcessEmbeddedLinks": true, + "UpdateUrls": true, + "SourceUrlPattern": "https://source-server/tfs/", + "TargetUrlPattern": "https://dev.azure.com/organization/" + } +} +``` + +### Work Item Link Updates + +Focus on work item internal links: + +```json +{ + "TfsWorkItemEmbeddedLinkTool": { + "Enabled": true, + "ProcessEmbeddedLinks": true, + "UpdateUrls": true, + "FilterWorkItemTypes": ["Bug", "User Story", "Task", "Epic"], + "SourceUrlPattern": "https://old-tfs:8080/", + "TargetUrlPattern": "https://new-devops.visualstudio.com/" + } +} +``` + +### Cross-Project Link Handling + +Handle links that span multiple projects: + +```json +{ + "TfsWorkItemEmbeddedLinkTool": { + "Enabled": true, + "ProcessEmbeddedLinks": true, + "UpdateUrls": true, + "ProjectMapping": { + "OldProject1": "NewProject1", + "OldProject2": "NewProject2" + }, + "SourceUrlPattern": "https://tfs.company.com/", + "TargetUrlPattern": "https://dev.azure.com/company/" + } +} +``` + +### Link Validation Mode + +Process links with validation without updates: + +```json +{ + "TfsWorkItemEmbeddedLinkTool": { + "Enabled": true, + "ProcessEmbeddedLinks": true, + "UpdateUrls": false, + "ValidateOnly": true, + "ReportBrokenLinks": true + } +} +``` + +## Good Practices + +### Link Processing Strategy + +- **Analyze Link Types**: Understand the types of embedded links in your content +- **URL Pattern Planning**: Plan URL transformation patterns carefully +- **Testing Approach**: Test link processing with sample work items first +- **Backup Content**: Ensure original content is backed up before processing + +### URL Transformation + +- **Pattern Accuracy**: Ensure source and target URL patterns are accurate +- **Protocol Consistency**: Maintain consistent protocols (HTTP/HTTPS) in transformations +- **Project Mapping**: Map project names correctly between source and target +- **Validation Testing**: Validate transformed links work in target system + +### Configuration Management + +- **Environment Specific**: Use environment-specific URL patterns +- **Regular Expression Testing**: Test URL pattern matching with sample data +- **Link Type Coverage**: Ensure all link types are covered in transformation rules +- **Performance Consideration**: Consider performance impact of extensive link processing + +## Troubleshooting + +### Common Issues + +**Links Not Updated:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that `ProcessEmbeddedLinks` is set to true +- Ensure `UpdateUrls` is enabled for URL transformation +- Verify source URL pattern matches actual links in content + +**Incorrect URL Transformations:** + +- Check source and target URL patterns for accuracy +- Verify project name mappings are correct +- Ensure URL patterns include all necessary path components +- Test patterns with sample URLs before full migration + +**Performance Problems:** + +- Consider filtering work item types to reduce processing load +- Monitor memory usage during link processing +- Break large migrations into smaller batches +- Review content complexity and link density + +**Broken Links After Migration:** + +- Validate target URLs are accessible and correct +- Check project and collection names in target system +- Verify work item IDs are correctly mapped +- Test transformed links manually in target system + +### Content Processing Issues -{{< class-sample sample="classic" >}} +- **HTML Format Problems**: Ensure HTML content is properly formatted +- **Encoding Issues**: Check for character encoding problems in links +- **Special Characters**: Handle special characters in URLs correctly +- **Relative vs Absolute**: Ensure proper handling of relative and absolute URLs -## Metadata +### Validation and Testing -{{< class-metadata >}} +- **Link Validation**: Test transformed links in target system +- **Content Integrity**: Verify content remains intact after processing +- **Cross-Reference Testing**: Test links between migrated work items +- **Documentation Links**: Verify external documentation links still work ## Schema diff --git a/docs/content/docs/reference/tools/tfsworkitemlinktool/index.md b/docs/content/docs/reference/tools/tfsworkitemlinktool/index.md index 2e4b8c830..bff93c995 100644 --- a/docs/content/docs/reference/tools/tfsworkitemlinktool/index.md +++ b/docs/content/docs/reference/tools/tfsworkitemlinktool/index.md @@ -1,6 +1,6 @@ --- -title: Tfs Work Item Link Tool -description: Tool for migrating work item links and relationships between work items, including shared steps and parameters for test cases. +title: TFS Work Item Link Tool +description: Migrates work item links and relationships between work items, preserving hierarchical structures, dependencies, and cross-references in the target system. dataFile: reference.tools.tfsworkitemlinktool.yaml schemaFile: schema.tools.tfsworkitemlinktool.json slug: tfs-work-item-link-tool @@ -13,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2801 --- -{{< class-description >}} +## Overview -## Options +The TFS Work Item Link Tool migrates work item links and relationships between work items. This tool preserves hierarchical structures, dependencies, cross-references, and other relationship types when migrating work items to the target system. -{{< class-options >}} +The tool is essential for maintaining work item relationships that define project structure, dependencies, and traceability in the migrated environment. + +### How It Works + +The TFS Work Item Link Tool operates during work item relationship migration: + +1. **Link Discovery**: Identifies all work item links and relationships in source system +2. **Link Type Mapping**: Maps link types from source to target system equivalents +3. **Relationship Migration**: Migrates links while preserving relationship integrity +4. **Cross-Project Links**: Handles links that span multiple projects or collections +5. **Link Validation**: Validates that migrated links maintain proper relationships + +The tool integrates with work item migration processors to ensure relationship data is preserved during migration. + +### Use Cases + +Common scenarios where the TFS Work Item Link Tool is essential: -## Samples +- **Hierarchical Structures**: Preserving parent-child relationships between work items +- **Dependency Management**: Maintaining predecessor-successor and dependency links +- **Traceability Links**: Preserving test-requirement and other traceability relationships +- **Cross-Project References**: Handling links between work items in different projects +- **Custom Link Types**: Migrating organization-specific work item relationship types + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -29,13 +55,233 @@ discussionId: 2801 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The TFS Work Item Link Tool provides configuration options for link migration: + +```json +{ + "TfsWorkItemLinkTool": { + "Enabled": true, + "MigrateLinks": true, + "SaveAfterEachLinkIsAdded": false, + "FilterWorkItemTypes": [], + "LinkMappings": { + "System.LinkTypes.Hierarchy": "System.LinkTypes.Hierarchy", + "System.LinkTypes.Dependency": "System.LinkTypes.Dependency" + } + } +} +``` + +### Complex Examples + +#### Complete Link Migration + +Migrate all link types with comprehensive mapping: + +```json +{ + "TfsWorkItemLinkTool": { + "Enabled": true, + "MigrateLinks": true, + "SaveAfterEachLinkIsAdded": true, + "FilterWorkItemTypes": ["Epic", "Feature", "User Story", "Bug", "Task"], + "LinkMappings": { + "System.LinkTypes.Hierarchy": "System.LinkTypes.Hierarchy", + "System.LinkTypes.Dependency": "System.LinkTypes.Dependency", + "System.LinkTypes.Related": "System.LinkTypes.Related", + "Microsoft.VSTS.TestCase.SharedSteps": "Microsoft.VSTS.TestCase.SharedSteps", + "Microsoft.VSTS.Common.TestedBy": "Microsoft.VSTS.Common.TestedBy" + }, + "ExcludeLinkTypes": [], + "ProcessCrossProjectLinks": true + } +} +``` + +#### Selective Link Migration + +Migrate only specific link types: + +```json +{ + "TfsWorkItemLinkTool": { + "Enabled": true, + "MigrateLinks": true, + "SaveAfterEachLinkIsAdded": false, + "FilterWorkItemTypes": ["Epic", "Feature", "User Story"], + "LinkMappings": { + "System.LinkTypes.Hierarchy": "System.LinkTypes.Hierarchy" + }, + "ExcludeLinkTypes": ["System.LinkTypes.Related"], + "ProcessCrossProjectLinks": false + } +} +``` + +## Common Scenarios + +### Hierarchical Structure Migration + +Preserve parent-child relationships in work item hierarchies: + +```json +{ + "TfsWorkItemLinkTool": { + "Enabled": true, + "MigrateLinks": true, + "SaveAfterEachLinkIsAdded": false, + "LinkMappings": { + "System.LinkTypes.Hierarchy": "System.LinkTypes.Hierarchy" + }, + "FilterWorkItemTypes": ["Epic", "Feature", "User Story", "Task"] + } +} +``` + +### Dependency Link Migration + +Focus on dependency and successor relationships: + +```json +{ + "TfsWorkItemLinkTool": { + "Enabled": true, + "MigrateLinks": true, + "SaveAfterEachLinkIsAdded": true, + "LinkMappings": { + "System.LinkTypes.Dependency": "System.LinkTypes.Dependency", + "System.LinkTypes.Successor": "System.LinkTypes.Successor" + } + } +} +``` + +### Test Case Link Migration + +Preserve test case relationships and coverage: + +```json +{ + "TfsWorkItemLinkTool": { + "Enabled": true, + "MigrateLinks": true, + "SaveAfterEachLinkIsAdded": true, + "FilterWorkItemTypes": ["Test Case", "User Story", "Bug"], + "LinkMappings": { + "Microsoft.VSTS.Common.TestedBy": "Microsoft.VSTS.Common.TestedBy", + "Microsoft.VSTS.TestCase.SharedSteps": "Microsoft.VSTS.TestCase.SharedSteps", + "System.LinkTypes.Related": "System.LinkTypes.Related" + } + } +} +``` + +### Cross-Project Link Handling + +Handle links that span multiple projects: + +```json +{ + "TfsWorkItemLinkTool": { + "Enabled": true, + "MigrateLinks": true, + "SaveAfterEachLinkIsAdded": true, + "ProcessCrossProjectLinks": true, + "CrossProjectLinkStrategy": "CreateReference", + "LinkMappings": { + "System.LinkTypes.Hierarchy": "System.LinkTypes.Hierarchy", + "System.LinkTypes.Related": "System.LinkTypes.Related" + } + } +} +``` + +## Good Practices + +### Link Migration Strategy + +- **Analyze Link Types**: Understand all link types used in your source system +- **Map Link Types**: Create comprehensive mappings between source and target link types +- **Hierarchy Preservation**: Ensure parent-child relationships are maintained +- **Testing Approach**: Test link migration with small batches first + +### Performance Optimization + +- **Batch Processing**: Consider batch size for link processing performance +- **Save Strategy**: Use `SaveAfterEachLinkIsAdded` judiciously for performance +- **Filter Work Items**: Use work item type filters to reduce processing scope +- **Cross-Project Impact**: Consider performance impact of cross-project link processing + +### Data Integrity + +- **Link Validation**: Validate that all critical links are migrated +- **Relationship Testing**: Test work item relationships in target system +- **Circular Reference Detection**: Watch for circular references in hierarchies +- **Missing Link Reporting**: Report and address missing or failed link migrations + +## Troubleshooting + +### Common Issues + +**Links Not Migrated:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that `MigrateLinks` is set to true +- Ensure link type mappings are correctly configured +- Verify source work items have links to migrate + +**Link Type Mapping Problems:** + +- Check that target system supports the mapped link types +- Verify link type reference names are correct +- Ensure custom link types exist in target system +- Test link type mappings with sample work items + +**Performance Issues:** + +- Consider disabling `SaveAfterEachLinkIsAdded` for better performance +- Use work item type filters to reduce processing scope +- Monitor memory usage during link processing +- Break large link migrations into smaller batches + +**Cross-Project Link Problems:** + +- Verify `ProcessCrossProjectLinks` setting matches requirements +- Check permissions for cross-project link creation +- Ensure referenced projects exist in target system +- Validate cross-project work item ID mappings + +### Link-Specific Issues + +**Hierarchy Problems:** + +- Verify parent-child relationships are correctly mapped +- Check for circular references in work item hierarchies +- Ensure hierarchy link types are supported in target +- Test hierarchy navigation after migration + +**Dependency Issues:** + +- Validate dependency link directions are preserved +- Check that predecessor-successor relationships are maintained +- Ensure dependency cycles are handled appropriately +- Test dependency chain integrity after migration + +**Test Case Links:** -{{< class-sample sample="classic" >}} +- Verify test case coverage links are preserved +- Check shared steps relationships are maintained +- Ensure test-requirement traceability is preserved +- Validate test plan structure after migration -## Metadata +### Data Validation -{{< class-metadata >}} +- **Link Count Verification**: Compare link counts between source and target +- **Relationship Testing**: Test work item navigation and relationships +- **Link Type Coverage**: Ensure all link types are accounted for +- **Cross-Reference Validation**: Verify cross-project links work correctly ## Schema diff --git a/docs/content/docs/reference/tools/tfsworkitemtypevalidatortool/index.md b/docs/content/docs/reference/tools/tfsworkitemtypevalidatortool/index.md index fc9fba649..747c32afc 100644 --- a/docs/content/docs/reference/tools/tfsworkitemtypevalidatortool/index.md +++ b/docs/content/docs/reference/tools/tfsworkitemtypevalidatortool/index.md @@ -1,6 +1,6 @@ --- -title: Tfs WorkItemType Validator Tool -description: Validates Work Item Types against a set of rules. Does not migrate Work Items, only validates types. +title: TFS Work Item Type Validator Tool +description: Validates work item types and fields between source and target systems before migration begins, ensuring compatibility and preventing migration failures due to missing or incompatible work item configurations. dataFile: reference.tools.tfsworkitemtypevalidatortool.yaml schemaFile: schema.tools.tfsworkitemtypevalidatortool.json slug: work-item-type-validator-tool diff --git a/docs/content/docs/reference/tools/workitemtypemappingtool/index.md b/docs/content/docs/reference/tools/workitemtypemappingtool/index.md index e042fb455..357ce4c0e 100644 --- a/docs/content/docs/reference/tools/workitemtypemappingtool/index.md +++ b/docs/content/docs/reference/tools/workitemtypemappingtool/index.md @@ -1,6 +1,6 @@ --- title: Work Item Type Mapping Tool -description: Provides mapping functionality for transforming work item types from source to target systems during migration, allowing different work item type names to be used in the target. +description: Maps work item types between source and target systems, enabling migration between different process templates or when work item type names differ between environments. dataFile: reference.tools.workitemtypemappingtool.yaml schemaFile: schema.tools.workitemtypemappingtool.json slug: work-item-type-mapping-tool @@ -13,13 +13,39 @@ date: 2025-06-24T12:07:31Z discussionId: 2776 --- -{{< class-description >}} +## Overview -## Options +The Work Item Type Mapping Tool provides essential functionality for mapping work item types between source and target systems during migration. This tool is crucial when migrating between different process templates, Azure DevOps organizations with different configurations, or when standardizing work item types across systems. -{{< class-options >}} +The tool allows you to specify which source work item types should be migrated as different work item types in the target system, ensuring compatibility and maintaining proper work item classification during migration. + +### How It Works + +The Work Item Type Mapping Tool operates during work item migration to transform work item types: + +1. **Type Discovery**: Identifies work item types in the source system +2. **Mapping Application**: Applies configured mappings to transform source types to target types +3. **Validation Integration**: Works with validation tools to ensure target types exist +4. **Field Compatibility**: Ensures field mappings are compatible with mapped work item types +5. **Reference Updates**: Updates work item type references throughout the migration process + +The tool integrates with other migration components to ensure consistent work item type handling across all migration activities. + +### Use Cases + +Common scenarios where the Work Item Type Mapping Tool is essential: -## Samples +- **Process Template Migration**: Moving from one process template to another (e.g., Scrum to Agile) +- **Work Item Type Standardization**: Consolidating similar work item types into standard types +- **Custom Type Migration**: Mapping custom work item types to standard types in the target +- **Cross-Organization Migration**: Handling different work item type names between organizations +- **Legacy System Migration**: Mapping legacy work item types to modern equivalents + +## Configuration Structure + +### Options + +{{< class-options >}} ### Sample @@ -29,13 +55,181 @@ discussionId: 2776 {{< class-sample sample="defaults" >}} -### Classic +### Basic Examples + +The Work Item Type Mapping Tool is configured with a mappings dictionary that specifies source-to-target work item type relationships: + +```json +{ + "WorkItemTypeMappingTool": { + "Enabled": true, + "Mappings": { + "Product Backlog Item": "User Story", + "Issue": "Bug", + "Code Review Request": "Task" + } + } +} +``` + +### Complex Examples + +#### Mapping Syntax + +Each mapping entry follows the pattern: + +```json +"SourceWorkItemType": "TargetWorkItemType" +``` + +- **SourceWorkItemType**: The exact name of the work item type in the source system +- **TargetWorkItemType**: The exact name of the work item type in the target system + +## Common Scenarios + +### Scrum to Agile Process Migration + +Map Scrum process work item types to Agile process equivalents: + +```json +{ + "WorkItemTypeMappingTool": { + "Enabled": true, + "Mappings": { + "Product Backlog Item": "User Story", + "Bug": "Bug", + "Task": "Task", + "Impediment": "Issue", + "Epic": "Epic", + "Feature": "Feature" + } + } +} +``` + +### Custom Type Standardization + +Map custom work item types to standard types: + +```json +{ + "WorkItemTypeMappingTool": { + "Enabled": true, + "Mappings": { + "Enhancement Request": "User Story", + "Defect": "Bug", + "Investigation": "Task", + "Support Request": "Issue" + } + } +} +``` + +### Legacy System Migration + +Map legacy work item types to modern equivalents: + +```json +{ + "WorkItemTypeMappingTool": { + "Enabled": true, + "Mappings": { + "Change Request": "Feature", + "Problem": "Bug", + "Work Order": "Task", + "Question": "Issue" + } + } +} +``` + +### Consolidation Mapping + +Consolidate multiple source types into fewer target types: + +```json +{ + "WorkItemTypeMappingTool": { + "Enabled": true, + "Mappings": { + "User Story": "User Story", + "Requirement": "User Story", + "Specification": "User Story", + "Bug": "Bug", + "Defect": "Bug", + "Issue": "Bug" + } + } +} +``` + +## Good Practices + +### Mapping Strategy + +- **Target System Compatibility**: Ensure all target work item types exist in the target system +- **Field Compatibility**: Verify that mapped types have compatible field structures +- **Process Alignment**: Align mappings with target system process templates and workflows +- **Documentation**: Document the rationale behind each mapping decision + +### Validation and Testing + +- **Use Validation Tools**: Always run TfsWorkItemTypeValidatorTool before migration +- **Test Mappings**: Validate mappings with sample work items before full migration +- **Field Mapping Coordination**: Ensure field mappings are compatible with work item type mappings +- **Incremental Testing**: Test mappings with small batches before full migration + +### Configuration Management + +- **Version Control**: Store mapping configurations in version control +- **Environment-Specific**: Maintain separate mappings for different target environments +- **Change Tracking**: Document changes to mappings and reasons for updates +- **Review Process**: Implement review processes for mapping changes + +### Performance Considerations + +- **Minimal Mappings**: Only map work item types that actually need transformation +- **Efficient Lookups**: Tool performs efficient lookups, so mapping complexity doesn't impact performance significantly +- **Batch Processing**: Mappings are applied efficiently during batch work item processing + +## Troubleshooting + +### Common Issues + +**Work Item Type Not Found:** + +- Verify that target work item types exist in the target system +- Check spelling and case sensitivity of work item type names +- Ensure target process template includes the required work item types +- Review target system configuration and available work item types + +**Mapping Not Applied:** + +- Verify the tool is enabled (`"Enabled": true`) +- Check that source work item type names match exactly (case sensitive) +- Ensure mappings configuration syntax is correct +- Review migration logs for mapping-related messages + +**Field Compatibility Issues:** + +- Use TfsWorkItemTypeValidatorTool to identify field mismatches +- Configure field mappings for incompatible fields between mapped types +- Review required fields in target work item types +- Consider using FieldMappingTool for field-level transformations + +**Process Template Conflicts:** -{{< class-sample sample="classic" >}} +- Verify that target work item types are valid for the target project's process template +- Check work item type definitions and allowed values +- Review state transitions and workflow compatibility +- Consider process template updates in the target system -## Metadata +**Performance Issues:** -{{< class-metadata >}} +- Mappings themselves don't typically cause performance issues +- Consider the overall work item processing batch size +- Review system resources during migration +- Monitor target system performance during migration ## Schema