Add support for commerce entities migration (#567)

* KX-21564 Ensure migration of customer and address entities

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* KX-21564 Cleanup

* KX-21564 Fix analyzer warning

* KX-21808 Ensure system fields prefixing (#556)

Ensure system fields prefixing

* KX-21565 MIgrate orders

* KX-21565 addressing review notes

* KX-21565 remove Kentico.Xperience.Admin package

* KX-21565 review changes

* KX-21565 remove comment

* KX-21565 fix net format

* initial wip

* copilot review changes, formatting

* update

* wording

* review update

* last dev review fix

* tw review changes

* missing comma

* add full migration example

* last update

* KX-21233 review changes and bum UMT package version (#574)

Co-authored-by: Josef Pohrom <josefp@kentico.com>

* add API comments for methods

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Josef Pohrom <josefp@kentico.com>
Co-authored-by: Josef Pohrom <j.pohrom@seznam.cz>
Co-authored-by: Jan Slezar <jans3@kentico.com>
Co-authored-by: jslezar <149673967+Honzaless@users.noreply.github.com>

Author: 6 people

.gitignore

@@ -8,3 +8,4 @@ appsettings.local.json
 .vs/
 *.sln.DotSettings.user
 Migration.Tool.CLI/appsettings.local.json_
+.nuget/nuget.exe

Migration.Tool.CLI/ConfigurationValidator.cs

@@ -157,6 +157,40 @@ public static IEnumerable<ValidationMessage> GetValidationErrors(IConfigurationR
         }
 
         #endregion
+
+        #region Commerce configuration validation
+
+        var commerceConfiguration = settings?.GetSection(ConfigurationNames.CommerceConfiguration);
+        if (commerceConfiguration is not null)
+        {
+            var commerceSiteNames = commerceConfiguration.GetSection(ConfigurationNames.CommerceSiteNames).Get<List<string>?>();
+            if (commerceSiteNames is null || commerceSiteNames.Count == 0)
+            {
+                yield return new ValidationMessage(ValidationMessageType.Error,
+                    $"'{ConfigurationNames.CommerceConfiguration}:{ConfigurationNames.CommerceSiteNames}' must contain at least one site name when '{ConfigurationNames.CommerceConfiguration}' is specified.");
+            }
+            else if (commerceSiteNames.Any(string.IsNullOrWhiteSpace))
+            {
+                yield return new ValidationMessage(ValidationMessageType.Error,
+                    $"'{ConfigurationNames.CommerceConfiguration}:{ConfigurationNames.CommerceSiteNames}' cannot contain empty or whitespace values.");
+            }
+
+            var systemFieldPrefix = commerceConfiguration.GetValue<string?>(ConfigurationNames.SystemFieldPrefix);
+            if (systemFieldPrefix is not null && string.IsNullOrWhiteSpace(systemFieldPrefix))
+            {
+                yield return new ValidationMessage(ValidationMessageType.Error,
+                    $"'{ConfigurationNames.CommerceConfiguration}:{ConfigurationNames.SystemFieldPrefix}' cannot be empty or whitespace when specified. Either provide a valid prefix value or remove the configuration to use the default.");
+            }
+
+            var orderStatuses = commerceConfiguration.GetValue<Dictionary<string, string[]>>(ConfigurationNames.OrderStatuses);
+            if (orderStatuses is not null && orderStatuses.Count == 0)
+            {
+                yield return new ValidationMessage(ValidationMessageType.Error,
+                    $"'{ConfigurationNames.CommerceConfiguration}:{ConfigurationNames.OrderStatuses}' must contain at least one order status from XbK counterpart.");
+            }
+        }
+
+        #endregion
     }
 
     #region "Helper methods"

Migration.Tool.CLI/README.md

@@ -153,3 +153,24 @@ public record MigrateContentTypeRestrictionsCommand : IRequest<CommandResult>, I
 
     public Type[] Dependencies => [typeof(MigrateSitesCommand), typeof(MigratePageTypesCommand), typeof(MigratePagesCommand)];
 }
+
+public record MigrateCustomersCommand : IRequest<CommandResult>, ICommand
+{
+    public static readonly int Rank = 1 + MigrateSitesCommand.Rank + MigrateCustomModulesCommand.Rank + MigrateUsersCommand.Rank + MigrateMembersCommand.Rank;
+
+    public static string Moniker => "customers";
+    public static string MonikerFriendly => "Customers and addresses";
+
+    public Type[] Dependencies => [typeof(MigrateSitesCommand), typeof(MigrateCustomModulesCommand), typeof(MigrateUsersCommand), typeof(MigrateMembersCommand)];
+}
+
+public record MigrateOrdersCommand : IRequest<CommandResult>, ICommand
+{
+    public static readonly int Rank = 1 + MigrateSitesCommand.Rank + MigrateCustomModulesCommand.Rank + MigrateUsersCommand.Rank + MigrateMembersCommand.Rank + MigrateCustomersCommand.Rank;
+
+    public static string Moniker => "orders";
+
+    public static string MonikerFriendly => "Orders";
+
+    public Type[] Dependencies => [typeof(MigrateSitesCommand), typeof(MigrateCustomModulesCommand), typeof(MigrateUsersCommand), typeof(MigrateMembersCommand), typeof(MigrateCustomersCommand)];
+}

Migration.Tool.Common/Commands.cs

@@ -0,0 +1,36 @@
+using System.Text.Json.Serialization;
+
+namespace Migration.Tool.Common;
+
+/// <summary>
+/// Configuration for commerce data migration.
+/// </summary>
+public class CommerceConfiguration
+{
+    [JsonPropertyName(ConfigurationNames.CommerceSiteNames)]
+    public List<string>? CommerceSiteNames { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.IncludeCustomerSystemFields)]
+    public List<string>? IncludeCustomerSystemFields { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.IncludeAddressSystemFields)]
+    public List<string>? IncludeAddressSystemFields { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.SystemFieldPrefix)]
+    public string? SystemFieldPrefix { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.IncludeOrderSystemFields)]
+    public List<string>? IncludeOrderSystemFields { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.IncludeOrderItemsSystemFields)]
+    public List<string>? IncludeOrderItemsSystemFields { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.IncludeOrderAddressSystemFields)]
+    public List<string>? IncludeOrderAddressSystemFields { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.OrderStatuses)]
+    public Dictionary<string, string[]> OrderStatuses { get; set; } = new(StringComparer.OrdinalIgnoreCase);
+
+    [JsonPropertyName(ConfigurationNames.KX13OrderFilter)]
+    public CommerceOrderFilterConfiguration? KX13OrderFilter { get; set; }
+}

Migration.Tool.Common/CommerceConfiguration.cs

@@ -0,0 +1,17 @@
+using System.Text.Json.Serialization;
+
+namespace Migration.Tool.Common;
+/// <summary>
+/// Configuration for filtering orders from KX13.
+/// </summary>
+public class CommerceOrderFilterConfiguration
+{
+    [JsonPropertyName(ConfigurationNames.OrderFromDate)]
+    public DateTime? OrderFromDate { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.OrderToDate)]
+    public DateTime? OrderToDate { get; set; }
+
+    [JsonPropertyName(ConfigurationNames.OrderStatusCodeNames)]
+    public List<string> OrderStatusCodeNames { get; set; } = [];
+}

Migration.Tool.Common/CommerceOrderFilterConfiguration.cs

@@ -74,4 +74,25 @@ public class ConfigurationNames
     public const string XbyKApiSettings = "XbyKApiSettings";
 
     #endregion
+
+    #region Commerce Configuration
+
+    public const string CommerceConfiguration = "CommerceConfiguration";
+    public const string CommerceSiteNames = "CommerceSiteNames";
+    public const string IncludeCustomerSystemFields = "IncludeCustomerSystemFields";
+    public const string IncludeAddressSystemFields = "IncludeAddressSystemFields";
+    public const string SystemFieldPrefix = "SystemFieldPrefix";
+    public const string IncludeOrderSystemFields = "IncludeOrderSystemFields";
+    public const string IncludeOrderItemsSystemFields = "IncludeOrderItemsSystemFields";
+    public const string IncludeOrderAddressSystemFields = "IncludeOrderAddressSystemFields";
+    public const string OrderStatuses = "OrderStatuses";
+    public const string KX13OrderFilter = "KX13OrderFilter";
+
+    #region KX13 Order Filter Configuration
+    public const string OrderFromDate = "OrderFromDate";
+    public const string OrderToDate = "OrderToDate";
+    public const string OrderStatusCodeNames = "OrderStatusCodeNames";
+    #endregion
+
+    #endregion
 }

Migration.Tool.Common/ConfigurationNames.cs

@@ -17,7 +17,7 @@
 
     <ItemGroup>
         <PackageReference Include="HtmlAgilityPack.NetCore" Version="1.5.0.1" />
-        <PackageReference Include="Kentico.Xperience.UMT" Version="4.0.1" />
+        <PackageReference Include="Kentico.Xperience.UMT" Version="4.1.0" />
         <PackageReference Include="MediatR" Version="12.4.1" />
         <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="8.0.0" />
         <PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.1" />

Migration.Tool.Common/Migration.Tool.Common.csproj

@@ -130,6 +130,18 @@ public class CommandParser : ICommandParser
                 continue;
             }
 
+            if (arg == $"--{MigrateCustomersCommand.Moniker}")
+            {
+                subcommands.Add(new MigrateCustomersCommand());
+                continue;
+            }
+
+            if (arg == $"--{MigrateOrdersCommand.Moniker}")
+            {
+                subcommands.Add(new MigrateOrdersCommand());
+                continue;
+            }
+
             throw new InvalidOperationException($"Unknown command '{arg}'");
         }
 
@@ -153,6 +165,8 @@ private void PrintCommandDescriptions()
         WriteCommandDesc($"starts migration of {Green(MigrateMembersCommand.MonikerFriendly)}", $"migrate --{MigrateMembersCommand.Moniker}");
         WriteCommandDesc($"starts migration of {Green(MigrateAttachmentsCommand.MonikerFriendly)}", $"migrate --{MigrateAttachmentsCommand.Moniker}");
         WriteCommandDesc($"starts migration of {Green(MigrateCustomModulesCommand.MonikerFriendly)}", $"migrate --{MigrateCustomModulesCommand.Moniker}");
+        WriteCommandDesc($"starts migration of {Green(MigrateCustomersCommand.MonikerFriendly)}", $"migrate --{MigrateCustomersCommand.Moniker}");
+        WriteCommandDesc($"starts migration of {Green(MigrateOrdersCommand.MonikerFriendly)}", $"migrate --{MigrateOrdersCommand.Moniker}");
         Console.WriteLine();
         Console.WriteLine($"Command {Green("patch")}: Applies migration patches to XbyK database. Patches are also applied at each run of {Green("migrate")}. Use this command to run patches without migration. " +
             $"Migration patches fix data problems caused by bugs in previous versions of Migration Tool. This command is idempotent - i.e. tolerant to multiple runs.");

Migration.Tool.Common/Services/CommandParser.cs

@@ -25,6 +25,9 @@ public class ToolConfiguration
     [ConfigurationKeyName(ConfigurationNames.EntityConfigurations)]
     public EntityConfigurations EntityConfigurations { get; set; } = [];
 
+    [ConfigurationKeyName(ConfigurationNames.CommerceConfiguration)]
+    public CommerceConfiguration? CommerceConfiguration { get; set; }
+
     [ConfigurationKeyName(ConfigurationNames.MigrateOnlyMediaFileInfo)]
     public bool? MigrateOnlyMediaFileInfo { get; set; } = false;