Skip to content

Commit 8e04476

Browse files
MrHinshMrHinsh
authored
Implement ExportWorkItemMappingTool (#3031)
## Implementation of `ExportWorkItemMappingTool` This tool is for saving mappings for work items between source and target. Work item IDs are saved as simple dictionary _source ID → target ID_. We need such a mappings for some post processing after work item migrations. In our case, we use wiki in source system, which will also be migrated to target. In the wiki, there are many links to backlog items. These links are written in the wiki as simple `#{workItemId}` – for example `#1234567`. So if we will have mappings from source to target, we can just replace those IDs and the wiki will be working in target system. I believe, some users can also find it useful for some post-processing. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Records source→target work‑item ID mappings as items are created/identified and persists them at migration end (configurable export tool with Enabled, TargetFile, PreserveExisting and validation). * **Tests** * Adds a mock export tool and wires it into test DI setups for unit tests. * **Documentation** * Adds docs and JSON schema for the export tool and updates ChangeSetMappingFile documentation. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 40c1462 + 3290e82 commit 8e04476

File tree

17 files changed

+349
-13
lines changed

17 files changed

+349
-13
lines changed

‎docs/data/classes/reference.tools.exportworkitemmappingtool.yaml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
optionsClassName: ExportWorkItemMappingToolOptions
2+
optionsClassFullName: MigrationTools.Tools.ExportWorkItemMappingToolOptions
3+
configurationSamples:
4+
- name: defaults
5+
order: 2
6+
description:
7+
code: There are no defaults! Check the sample for options!
8+
sampleFor: MigrationTools.Tools.ExportWorkItemMappingToolOptions
9+
- name: sample
10+
order: 1
11+
description:
12+
code: There is no sample, but you can check the classic below for a general feel.
13+
sampleFor: MigrationTools.Tools.ExportWorkItemMappingToolOptions
14+
- name: classic
15+
order: 3
16+
description:
17+
code: >-
18+
{
19+
"$type": "ExportWorkItemMappingToolOptions",
20+
"Enabled": false,
21+
"TargetFile": "",
22+
"PreserveExisting": true
23+
}
24+
sampleFor: MigrationTools.Tools.ExportWorkItemMappingToolOptions
25+
description: >-
26+
Tool for exporting mappings of work item IDs from source to target.
27+
Work item migration processor uses this tool to record work item ID mappings.
28+
The mappings will be saved to file defined in options at the end of the migration.
29+
className: ExportWorkItemMappingTool
30+
typeName: Tools
31+
options:
32+
- parameterName: Enabled
33+
type: Boolean
34+
description: If set to `true` then the tool will run. Set to `false` and the processor will not run.
35+
defaultValue: true
36+
isRequired: false
37+
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
38+
- parameterName: PreserveExisting
39+
type: Boolean
40+
description: >-
41+
Indicates whether existing mappings in the target file should be preserved when saving new mappings.
42+
Default value is `true`.
43+
defaultValue: true
44+
isRequired: false
45+
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
46+
- parameterName: TargetFile
47+
type: String
48+
description: Path to file, where work item mapping will be saved.
49+
defaultValue: ''
50+
isRequired: false
51+
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
52+
status: missing XML code comments
53+
processingTarget: missing XML code comments
54+
classFile: src/MigrationTools/Tools/ExportWorkItemMappingTool.cs
55+
optionsClassFile: src/MigrationTools/Tools/ExportWorkItemMappingToolOptions.cs

‎docs/data/classes/reference.tools.tfschangesetmappingtool.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@ typeName: Tools
4949
options:
5050
- parameterName: ChangeSetMappingFile
5151
type: String
52-
description: missing XML code comments
53-
defaultValue: missing XML code comments
52+
description: Path to changeset mapping file.
53+
defaultValue: null
5454
isRequired: false
5555
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
5656
- parameterName: Enabled

‎docs/static/schema/configuration.schema.json‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1731,6 +1731,27 @@
17311731
"CommonTools": {
17321732
"type": "object",
17331733
"properties": {
1734+
"ExportWorkItemMappingTool": {
1735+
"title": "ExportWorkItemMappingTool",
1736+
"description": "Tool for exporting mappings of work item IDs from source to target.\r\n Work item migration processor uses this tool to record work item ID mappings.\r\n The mappings will be saved to file defined in options at the end of the migration.",
1737+
"type": "object",
1738+
"properties": {
1739+
"Enabled": {
1740+
"description": "If set to `true` then the tool will run. Set to `false` and the processor will not run.",
1741+
"type": "boolean",
1742+
"default": "true"
1743+
},
1744+
"PreserveExisting": {
1745+
"description": "Indicates whether existing mappings in the target file should be preserved when saving new mappings.\r\n Default value is `true`.",
1746+
"type": "boolean",
1747+
"default": "true"
1748+
},
1749+
"TargetFile": {
1750+
"description": "Path to file, where work item mapping will be saved.",
1751+
"type": "string"
1752+
}
1753+
}
1754+
},
17341755
"FieldMappingTool": {
17351756
"title": "FieldMappingTool",
17361757
"description": "Tool for applying field mapping transformations to work items during migration, supporting various field mapping strategies like direct mapping, regex transformations, and value lookups.",
@@ -2229,8 +2250,9 @@
22292250
"default": "true"
22302251
},
22312252
"ChangeSetMappingFile": {
2232-
"description": "missing XML code comments",
2233-
"type": "string"
2253+
"description": "Path to changeset mapping file.",
2254+
"type": "string",
2255+
"default": "null"
22342256
}
22352257
}
22362258
},

‎docs/static/schema/schema.tools.exportworkitemmappingtool.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://devopsmigration.io/schema/schema.tools.exportworkitemmappingtool.json",
4+
"title": "ExportWorkItemMappingTool",
5+
"description": "Tool for exporting mappings of work item IDs from source to target.\r\n Work item migration processor uses this tool to record work item ID mappings.\r\n The mappings will be saved to file defined in options at the end of the migration.",
6+
"type": "object",
7+
"properties": {
8+
"Enabled": {
9+
"description": "If set to `true` then the tool will run. Set to `false` and the processor will not run.",
10+
"type": "boolean",
11+
"default": "true"
12+
},
13+
"PreserveExisting": {
14+
"description": "Indicates whether existing mappings in the target file should be preserved when saving new mappings.\r\n Default value is `true`.",
15+
"type": "boolean",
16+
"default": "true"
17+
},
18+
"TargetFile": {
19+
"description": "Path to file, where work item mapping will be saved.",
20+
"type": "string"
21+
}
22+
}
23+
}

‎docs/static/schema/schema.tools.tfschangesetmappingtool.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@
66
"type": "object",
77
"properties": {
88
"ChangeSetMappingFile": {
9-
"description": "missing XML code comments",
10-
"type": "string"
9+
"description": "Path to changeset mapping file.",
10+
"type": "string",
11+
"default": "null"
1112
},
1213
"Enabled": {
1314
"description": "If set to `true` then the tool will run. Set to `false` and the processor will not run.",

‎src/MigrationTools.Clients.AzureDevops.Rest.Tests/Processors/AzureDevOpsProcessorTests.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ protected AzureDevOpsPipelineProcessor GetAzureDevOpsPipelineProcessor(AzureDevO
2525
services.AddSingleton<CommonTools>();
2626
services.AddSingleton<IFieldMappingTool, MockFieldMappingTool>();
2727
services.AddSingleton<IWorkItemTypeMappingTool, MockWorkItemTypeMappingTool>();
28+
services.AddSingleton<IExportWorkItemMappingTool, MockExportWorkItemMappingTool>();
2829
services.AddSingleton<IStringManipulatorTool, StringManipulatorTool>();
2930

3031
services.AddSingleton<AzureDevOpsPipelineProcessor>();

‎src/MigrationTools.Clients.TfsObjectModel.Tests/Processors/TfsProcessorTests.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ protected TfsTeamSettingsProcessor GetTfsTeamSettingsProcessor(TfsTeamSettingsPr
3838
services.AddSingleton<CommonTools>();
3939
services.AddSingleton<IFieldMappingTool, MockFieldMappingTool>();
4040
services.AddSingleton<IWorkItemTypeMappingTool, MockWorkItemTypeMappingTool>();
41+
services.AddSingleton<IExportWorkItemMappingTool, MockExportWorkItemMappingTool>();
4142
services.AddSingleton<IStringManipulatorTool, StringManipulatorTool>();
4243
services.AddSingleton<IWorkItemQueryBuilderFactory, WorkItemQueryBuilderFactory>();
4344
services.AddSingleton<IWorkItemQueryBuilder, WorkItemQueryBuilder>();
@@ -107,6 +108,7 @@ protected TfsSharedQueryProcessor GetTfsSharedQueryProcessor(TfsSharedQueryProce
107108
services.AddSingleton<CommonTools>();
108109
services.AddSingleton<IFieldMappingTool, MockFieldMappingTool>();
109110
services.AddSingleton<IWorkItemTypeMappingTool, MockWorkItemTypeMappingTool>();
111+
services.AddSingleton<IExportWorkItemMappingTool, MockExportWorkItemMappingTool>();
110112
services.AddSingleton<IStringManipulatorTool, StringManipulatorTool>();
111113
services.TryAddScoped<IWorkItemQueryBuilderFactory, WorkItemQueryBuilderFactory>();
112114

‎src/MigrationTools.Clients.TfsObjectModel/Processors/TfsWorkItemMigrationProcessor.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,7 @@ protected override void InternalExecute()
233233
}
234234
finally
235235
{
236+
CommonTools.ExportWorkItemMapping.SaveMappings();
236237
if (Options.FixHtmlAttachmentLinks)
237238
{
238239
CommonTools.EmbededImages?.ProcessorExecutionEnd(null);
@@ -601,6 +602,7 @@ private async Task ProcessWorkItemAsync(WorkItemData sourceWorkItem, ProgressTim
601602
}
602603
if (targetWorkItem != null)
603604
{
605+
CommonTools.ExportWorkItemMapping.AddMapping(sourceWorkItem.Id, targetWorkItem.Id);
604606
targetWorkItem.ToWorkItem().Close();
605607
}
606608
if (sourceWorkItem != null)

‎src/MigrationTools.Clients.TfsObjectModel/Tools/TfsChangeSetMappingToolOptions.cs‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1-
using System;
2-
using MigrationTools.Enrichers;
3-
using MigrationTools.Tools.Infrastructure;
1+
using MigrationTools.Tools.Infrastructure;
42

53
namespace MigrationTools.Tools
64
{
75
public class TfsChangeSetMappingToolOptions : ToolOptions
86
{
9-
7+
/// <summary>
8+
/// Path to changeset mapping file.
9+
/// </summary>
10+
/// <default>null</default>
1011
public string ChangeSetMappingFile { get; set; }
11-
1212
}
13-
}
13+
}

‎src/MigrationTools.Clients.TfsObjectModel/Tools/TfsStaticTools.cs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ public class TfsCommonTools : CommonTools
2222
/// <param name="TfsGitRepositoryTool">Tool for git repository operations</param>
2323
/// <param name="StringManipulatorTool">Tool for string field manipulation</param>
2424
/// <param name="workItemTypeMapping">Tool for work item type mapping</param>
25+
/// <param name="exportWorkItemMapping">Tool for exporting work item mapping.</param>
2526
/// <param name="workItemTypeValidatorTool">Tool for work item type validation.</param>
2627
/// <param name="fieldMappingTool">Tool for field mapping operations</param>
2728
public TfsCommonTools(
@@ -37,9 +38,10 @@ public TfsCommonTools(
3738
TfsGitRepositoryTool TfsGitRepositoryTool,
3839
IStringManipulatorTool StringManipulatorTool,
3940
IWorkItemTypeMappingTool workItemTypeMapping,
41+
IExportWorkItemMappingTool exportWorkItemMapping,
4042
TfsWorkItemTypeValidatorTool workItemTypeValidatorTool,
4143
IFieldMappingTool fieldMappingTool
42-
) : base(StringManipulatorTool, workItemTypeMapping,fieldMappingTool)
44+
) : base(StringManipulatorTool, workItemTypeMapping, exportWorkItemMapping, fieldMappingTool)
4345
{
4446
UserMapping = userMappingEnricher;
4547
Attachment = attachmentEnricher;

0 commit comments

Comments
 (0)