Merge pull request #1108 from solidify/feature/expose-revision-defer-as-config-parameter

Expose config parameter: DeferForRevisionsSucceedingAttachmentImportsMilliseconds

Author: Alexander-Hjelm

docs/config.md

@@ -38,6 +38,7 @@ The migration configuration file is defined in a json file with the properties d
 |**suppress-notifications**|False|boolean|Set to True to suppress all notifications in Azure DevOps about created and updated Work Items. Default = False.|
 |**include-development-links**|False|boolean|Set to True to migrated commit links from Jira to Azure DevOps. You will also need to fill out the **repository-map** property. Default = False.|
 |**sleep-time-between-revision-import-milliseconds**|False|integer|How many milliseconds to sleep between each revision import. Use this if throttling is an issue for ADO Services. Default = 0 (no sleep).|
+|**buffer-revisions-succeeding-attachment-imports-milliseconds**|False|integer|How many milliseconds to buffer each subsequent revision if there is a negative revision timestamp offset. Increase this if you get problems with VS402625 error messages. Default = 5 (ms).|
 |**process-template**|False|string|Process template in the target DevOps project. Supported values: Scrum, Agile or CMMI. Default = "Scrum".|
 |**link-map**|True|json|List of **links** to map between Jira and Azure DevOps/TFS work item link types.|
 |**type-map**|True|json|List of the work item **types** you want to migrate from Jira to Azure DevOps/TFS.|

docs/faq.md

@@ -430,7 +430,26 @@ curl -D-
  "http://johnie:8081/rest/api/2/search"
 ```
 
-## 19. Sprint names are corrupted. ADO Iteration paths are named "[ synced = false  ]"
+## 19. I get the error message "VS402625: Dates must be increasing with each revision."
+
+ADO can sometimes add a few milliseconds to the work item changedDate when adding an attachment. This can have unfortunate consequences if the tool attempts to import a subsequent revision with a changedDate that is less than the previous reivison that was successfully imported.
+
+You may end up receiving an error message similar to this one:
+
+```txt
+[E][18:32:06] VS402625: Dates must be increasing with each revision.
+[E][18:32:06] Work Item 15312 failed to save.
+```
+
+The solution is to buffer the subsequent revision's changedDate by a few miliseconds. This is the purpose of the configuration parameter `buffer-revisions-succeeding-attachment-imports-milliseconds` (default: 5). Add this parameter to your `config.json` file and try increasing the value by 1 (5, 6, 7, and so on...) until the import succeeds without errors.
+
+Example `config.json`:
+
+```json
+  "buffer-revisions-succeeding-attachment-imports-milliseconds": 6,
+```
+
+## 20. Sprint names are corrupted. ADO Iteration paths are named "[ synced = false  ]"
 
 The issue is usually that a custom field has been defined in Jira which is also named "Sprint", and the tool is picking up this field instead of the default Srpint field.
 
@@ -458,9 +477,7 @@ It could be worth trying this mapping when running against Jira Cloud too:
 
 It seems that for jira server, the field IDs can different between different developer instances. You can use the Get Fields endpoint to find out which field ID (customfield_xxxxx) is used by Sprint in your instance: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about
 
-Give it a try and let me know if it still does not work.
-
-## 20. Azure DevOps Rate and usage limits (ADO Cloud only)
+## 21. Azure DevOps Rate and usage limits (ADO Cloud only)
 
 In the unlikely event that you experience issues with being rate limited by Azure DevOps, we always recommend the following procedure:
 

src/WorkItemMigrator/Migration.Common/Config/ConfigJson.cs

@@ -81,6 +81,9 @@ public class ConfigJson
         [JsonProperty(PropertyName = "include-jira-css-styles")]
         public bool IncludeJiraCssStyles { get; set; } = false;
 
+        [JsonProperty(PropertyName = "buffer-revisions-succeeding-attachment-imports-milliseconds")]
+        public int BufferRevisionsSucceedingAttachmentImportsMilliseconds { get; set; } = 5;
+
         [JsonProperty(PropertyName = "ignore-empty-revisions")]
         public bool IgnoreEmptyRevisions { get; set; } = false;
 

src/WorkItemMigrator/WorkItemImport/Agent.cs

@@ -67,7 +67,7 @@ public bool ImportRevision(WiRevision rev, WorkItem wi, Settings settings)
                 if (rev.Index == 0)
                     _witClientUtils.EnsureClassificationFields(rev);
 
-                _witClientUtils.EnsureDateFields(rev, wi);
+                _witClientUtils.EnsureDateFields(rev, wi, settings.BufferRevisionsSucceedingAttachmentImportsMilliseconds);
                 _witClientUtils.EnsureAuthorFields(rev);
                 _witClientUtils.EnsureAssigneeField(rev, wi);
                 _witClientUtils.EnsureFieldsOnStateChange(rev, wi);

src/WorkItemMigrator/WorkItemImport/ImportCommandLine.cs

@@ -93,7 +93,8 @@ private bool ExecuteMigration(CommandOption token, CommandOption url, CommandOpt
                     IncludeLinkComments = config.IncludeLinkComments,
                     IncludeDevelopmentLinks = config.IncludeDevelopmentLinks,
                     FieldMap = config.FieldMap,
-                    SuppressNotifications = config.SuppressNotifications
+                    SuppressNotifications = config.SuppressNotifications,
+                    BufferRevisionsSucceedingAttachmentImportsMilliseconds = config.BufferRevisionsSucceedingAttachmentImportsMilliseconds
                 };
 
                 // initialize Azure DevOps/TFS connection. Creates/fetches project, fills area and iteration caches.

src/WorkItemMigrator/WorkItemImport/Settings.cs

@@ -22,5 +22,6 @@ public Settings(string account, string project, string pat)
         public bool IncludeDevelopmentLinks { get; internal set; }
         public FieldMap FieldMap { get; internal set; }
         public bool SuppressNotifications { get; internal set; }
+        public int BufferRevisionsSucceedingAttachmentImportsMilliseconds { get; set; }
     }
 }

src/WorkItemMigrator/WorkItemImport/WitClient/WitClientUtils.cs

@@ -240,7 +240,7 @@ public void EnsureAssigneeField(WiRevision rev, WorkItem wi)
             rev.Fields.Add(new WiField() { ReferenceName = WiFieldReference.AssignedTo, Value = assignedTo });
         }
 
-        public void EnsureDateFields(WiRevision rev, WorkItem wi)
+        public void EnsureDateFields(WiRevision rev, WorkItem wi, int bufferMS)
         {
             if (rev == null)
             {
@@ -271,8 +271,8 @@ public void EnsureDateFields(WiRevision rev, WorkItem wi)
                 else
                 {
                     // ADO can add a few milliseconds to work item createdDate when adding an attachment, hence adding more here to the revision time
-                    rev.Fields.Add(new WiField() { ReferenceName = WiFieldReference.ChangedDate, Value = rev.Time.AddMilliseconds(5).ToString("o") });
-                    wi.Fields[WiFieldReference.ChangedDate] = rev.Time.AddMilliseconds(5);
+                    rev.Fields.Add(new WiField() { ReferenceName = WiFieldReference.ChangedDate, Value = rev.Time.AddMilliseconds(bufferMS).ToString("o") });
+                    wi.Fields[WiFieldReference.ChangedDate] = rev.Time.AddMilliseconds(bufferMS);
                 }
             }
 

src/WorkItemMigrator/tests/Migration.Wi-Import.Tests/WitClient/WitClientUtilsTests.cs

@@ -280,7 +280,7 @@ public void When_calling_ensure_date_fields_with_empty_args_Then_an_exception_is
             MockedWitClientWrapper witClientWrapper = new MockedWitClientWrapper();
             WitClientUtils wiUtils = new WitClientUtils(witClientWrapper);
             Assert.That(
-                () => wiUtils.EnsureDateFields(null, null),
+                () => wiUtils.EnsureDateFields(null, null, 0),
                 Throws.InstanceOf<ArgumentException>());
         }
 
@@ -303,7 +303,7 @@ public void When_calling_ensure_date_fields_with_first_revision_Then_dates_are_a
 
             createdWI.Fields[WiFieldReference.ChangedDate] = now;
 
-            wiUtils.EnsureDateFields(rev, createdWI);
+            wiUtils.EnsureDateFields(rev, createdWI, 0);
 
             Assert.Multiple(() =>
             {