Add fieldMapMode to FieldToFieldMap and update related documentation (#2957)

This pull request adds a new `fieldMapMode` option to the
FieldToFieldMap configuration, allowing users to specify how fields are
mapped during migration—either from the source to the target system or
between target fields. The update includes code changes, schema updates,
documentation, and example configurations to support this new feature.

**Field Mapping Mode Feature:**

* Introduced the `FieldMapMode` enum with `SourceToTarget` and
`TargetToTarget` options, and added the `fieldMapMode` property to
`FieldToFieldMapOptions`, defaulting to `SourceToTarget`. This allows
users to control the direction and context of field mapping.
[[1]](diffhunk://#diff-81182bfd75331f6d5d0de7c559392ef9f61f2c0b7636cde99743276795186f21R3-R31)
[[2]](diffhunk://#diff-81182bfd75331f6d5d0de7c559392ef9f61f2c0b7636cde99743276795186f21R53)
* Updated the `InternalExecute` method in `FieldToFieldMap.cs` to use
the new `fieldMapMode` property, determining whether to map from the
source or target field, and improved logging to reflect the mapping mode
used.

**Schema and Documentation Updates:**

* Added `fieldMapMode` to relevant JSON schema files
(`configuration.schema.json`, `schema.fieldmaps.fieldtofieldmap.json`,
`schema.tools.fieldmappingtool.json`) with descriptions and default
values, ensuring configuration validation and discoverability.
[[1]](diffhunk://#diff-52f03d9f526916598fa826728ae4633eae3ac279b3dd76548f1e6fdb93686ae4R1925-R1929)
[[2]](diffhunk://#diff-08b834ba0de2813a02c071d1dfb9f98d0c6ac07c677008117f4d347c57fe42ffR20-R24)
[[3]](diffhunk://#diff-8f718075f4ee2192874e43b363e8f395b1d9beb3f3024abd75a21fb64ed2f306R192-R196)
* Updated documentation and YAML reference files to include the new
`fieldMapMode` option in configuration samples and parameter lists,
providing clear guidance and usage examples.
[[1]](diffhunk://#diff-996da70e5724b7d991c1ad90fe0dc3d90658e67c22b3f787a8e5f3798ca2c507R57)
[[2]](diffhunk://#diff-996da70e5724b7d991c1ad90fe0dc3d90658e67c22b3f787a8e5f3798ca2c507R89-R94)
[[3]](diffhunk://#diff-d7cdd7597baae20026f0d5712a1fbba7d3daf959928a6001720f6d93e8d3c5f3R71)

**Miscellaneous:**

* Added a missing `using System.Windows.Forms;` directive in
`FieldToFieldMap.cs`

Author: MrHinsh

docs/content/docs/how-to/migrating-plans-and-suites/index.md

@@ -68,6 +68,7 @@ The important bits:
         "FieldMaps": [
           {
             "FieldMapType": "FieldToFieldMap",
+            "fieldMapMode": "TargetToTarget",
             "sourceField": "Custom.ReflectedWorkItemId",
             "targetField": "Microsoft.VSTS.Build.IntegrationBuild",
             "defaultValue": "",

docs/data/classes/reference.fieldmaps.fieldtofieldmap.yaml

@@ -54,6 +54,7 @@ configurationSamples:
   code: >-
     {
       "$type": "FieldToFieldMapOptions",
+      "fieldMapMode": "SourceToTarget",
       "sourceField": "Microsoft.VSTS.Common.BacklogPriority",
       "targetField": "Microsoft.VSTS.Common.StackRank",
       "defaultValue": "42",
@@ -85,6 +86,12 @@ options:
   defaultValue: missing XML code comments
   isRequired: false
   dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
+- parameterName: fieldMapMode
+  type: FieldMapMode
+  description: Gets or sets the mode of field mapping to be applied during migration. SourceToTarget will get data from the source system and apply it to the target. TargetToTarget will move data between the target fields.
+  defaultValue: SourceToTarget
+  isRequired: false
+  dotNetType: MigrationTools.Tools.FieldMapMode, MigrationTools, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
 - parameterName: sourceField
   type: String
   description: Gets or sets the name of the source field to copy data from during migration.

docs/static/schema/configuration.schema.json

@@ -1922,6 +1922,11 @@
                               "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                               "type": "boolean"
                             },
+                            "fieldMapMode": {
+                              "description": "Gets or sets the mode of field mapping to be applied during migration. SourceToTarget will get data from the source system and apply it to the target. TargetToTarget will move data between the target fields.",
+                              "type": "string",
+                              "default": "SourceToTarget"
+                            },
                             "sourceField": {
                               "description": "Gets or sets the name of the source field to copy data from during migration.",
                               "type": "string"

docs/static/schema/schema.fieldmaps.fieldtofieldmap.json

@@ -17,6 +17,11 @@
       "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
       "type": "boolean"
     },
+    "fieldMapMode": {
+      "description": "Gets or sets the mode of field mapping to be applied during migration. SourceToTarget will get data from the source system and apply it to the target. TargetToTarget will move data between the target fields.",
+      "type": "string",
+      "default": "SourceToTarget"
+    },
     "sourceField": {
       "description": "Gets or sets the name of the source field to copy data from during migration.",
       "type": "string"

docs/static/schema/schema.tools.fieldmappingtool.json

@@ -189,6 +189,11 @@
                   "description": "If set to `true` then the Fieldmap will run. Set to `false` and the processor will not run.",
                   "type": "boolean"
                 },
+                "fieldMapMode": {
+                  "description": "Gets or sets the mode of field mapping to be applied during migration. SourceToTarget will get data from the source system and apply it to the target. TargetToTarget will move data between the target fields.",
+                  "type": "string",
+                  "default": "SourceToTarget"
+                },
                 "sourceField": {
                   "description": "Gets or sets the name of the source field to copy data from during migration.",
                   "type": "string"

src/MigrationTools.Clients.TfsObjectModel/Tools/FieldMappingTool/FieldMaps/FieldToFieldMap.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Windows.Forms;
 using Microsoft.Extensions.Logging;
 using Microsoft.TeamFoundation.WorkItemTracking.Client;
 using MigrationTools.Tools;
@@ -40,14 +41,23 @@ internal override void InternalExecute(WorkItem source, WorkItem target)
         {
             return;
         }
-
-        var value = Convert.ToString(source.Fields[Config.sourceField]?.Value);
+        string value;
+        switch (Config.fieldMapMode)
+        {
+            case FieldMapMode.SourceToTarget:
+                value = Convert.ToString(source.Fields[Config.sourceField]?.Value);
+                break;
+            case FieldMapMode.TargetToTarget:
+                value = Convert.ToString(target.Fields[Config.sourceField]?.Value);
+                break;
+            default:
+                throw new ArgumentOutOfRangeException();
+        }
         if (string.IsNullOrEmpty(value) && Config.defaultValue is not null)
         {
             value = Config.defaultValue;
         }
-
         target.Fields[Config.targetField].Value = value;
-        Log.LogDebug("FieldToFieldMap: [UPDATE] field mapped {0}:{1} to {2}:{3}", source.Id, Config.sourceField, target.Id, Config.targetField);
+        Log.LogDebug("FieldToFieldMap: [UPDATE] field mapped {0}:{1} to {2}:{3} as {4}", source.Id, Config.sourceField, target.Id, Config.targetField, Config.fieldMapMode.ToString());
     }
-}
+}

src/MigrationTools/Tools/FieldMappingTool/FieldMaps/FieldtoFieldMapOptions.cs

@@ -1,26 +1,44 @@
 
 using System.Collections.Generic;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
 using MigrationTools.Tools.Infrastructure;
 
 namespace MigrationTools.Tools
 {
+
+    [JsonConverter(typeof(StringEnumConverter))]
+    public enum FieldMapMode
+    {
+        SourceToTarget = 0,
+        TargetToTarget = 1
+    }
+
+
     /// <summary>
     /// Just want to map one field to another? This is the one for you.
     /// </summary>
     /// <status>ready</status>
     /// <processingtarget>Work Item Field</processingtarget>
     public class FieldToFieldMapOptions : FieldMapOptions
     {
+
+        /// <summary>
+        /// Gets or sets the mode of field mapping to be applied during migration. SourceToTarget will get data from the source system and apply it to the target. TargetToTarget will move data between the target fields.
+        /// </summary>
+        /// <default>SourceToTarget</default>
+        public FieldMapMode fieldMapMode { get; set; } = FieldMapMode.SourceToTarget;
+
         /// <summary>
         /// Gets or sets the name of the source field to copy data from during migration.
         /// </summary>
         public string sourceField { get; set; }
-        
+
         /// <summary>
         /// Gets or sets the name of the target field to copy data to during migration.
         /// </summary>
         public string targetField { get; set; }
-        
+
         /// <summary>
         /// Gets or sets the default value to use when the source field is empty or null.
         /// </summary>
@@ -32,6 +50,7 @@ public void SetExampleConfigDefaults()
             sourceField = "System.StackRank";
             targetField = "System.Rank";
             defaultValue = "1000";
+            fieldMapMode = FieldMapMode.SourceToTarget;
         }
     }
-}
+}