Merge pull request #550 from Kentico/develop

akfakmot · web-flow · commit 59f99eda914a · 2025-11-26T17:16:00.000+01:00
Release 3.21.0
diff --git a/KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs b/KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs
@@ -335,7 +335,6 @@ private async Task MigratePages()
                         ? (Guid?)null
                         : spoiledGuidContext.EnsureNodeGuid(ksNodeParent);
 
-                    DataClassInfo targetClass = null!;
                     var classMapping = classMappingProvider.GetMapping(ksNodeClass.ClassName);
 
                     var producedReusableSchemas = reusableSchemaBuilders.Where(x =>
@@ -348,17 +347,12 @@ private async Task MigratePages()
                         continue;
                     }
 
-                    targetClass = classMapping != null
-                        ? DataClassInfoProvider.ProviderObject.Get(classMapping.TargetClassName)
-                        : DataClassInfoProvider.ProviderObject.Get(ksNodeClass.ClassGUID);
-
                     var results = mapper.Map(new CmsTreeMapperSource(
                         ksNode,
                         safeNodeName,
                         ksSite.SiteGUID,
                         nodeParentGuid,
                         cultureCodeToLanguageGuid!,
-                        targetClass?.ClassFormDefinition,
                         ksNodeClass.ClassFormDefinition,
                         migratedDocuments,
                         ksSite,
@@ -424,11 +418,13 @@ private async Task MigratePages()
                             }
                         }
 
+                        var targetClassInfo = contentItemDirective!.TargetClassInfo;
+
                         if (contentItemDirective is not DropDirective)
                         {
                             AssertVersionStatusRule(commonDataInfos);
 
-                            if (webPageItemInfo != null && targetClass is { ClassWebPageHasUrl: true })
+                            if (webPageItemInfo != null && targetClassInfo is { ClassWebPageHasUrl: true })
                             {
                                 await GenerateDefaultPageUrlPath(ksNode, webPageItemInfo);
                                 if (!contentItemDirective!.RegenerateUrlPath)
diff --git a/KVA/Migration.Tool.Source/Mappers/ContentItemMapper.cs b/KVA/Migration.Tool.Source/Mappers/ContentItemMapper.cs
@@ -39,7 +39,6 @@ public record CmsTreeMapperSource(
     Guid SiteGuid,
     Guid? NodeParentGuid,
     Dictionary<string, Guid> CultureToLanguageGuid,
-    string? TargetFormDefinition,
     string SourceFormDefinition,
     List<ICmsDocument> MigratedDocuments,
     ICmsSite SourceSite,
@@ -91,51 +90,46 @@ WorkspaceService workspaceService
 
     protected override IEnumerable<IUmtModel> MapInternal(CmsTreeMapperSource source)
     {
-        (var cmsTree, string safeNodeName, var siteGuid, var nodeParentGuid, var cultureToLanguageGuid, string? targetFormDefinition, string sourceFormDefinition, var migratedDocuments, var sourceSite, bool deferred) = source;
+        (var cmsTree, string safeNodeName, var siteGuid, var nodeParentGuid, var cultureToLanguageGuid, string sourceFormDefinition, var migratedDocuments, var sourceSite, bool deferred) = source;
         logger.LogTrace("Mapping {Value}", new { cmsTree.NodeAliasPath, cmsTree.NodeName, cmsTree.NodeGUID, cmsTree.NodeSiteID });
 
         var childNodes = modelFacade.Select<ICmsTree>("NodeParentID = @nodeID", "NodeOrder", new SqlParameter("nodeID", cmsTree.NodeID))!.ToArray();
 
         var sourceNodeClass = modelFacade.SelectById<ICmsClass>(cmsTree.NodeClassID) ?? throw new InvalidOperationException($"Fatal: node class is missing, class id '{cmsTree.NodeClassID}'");
         var mapping = classMappingProvider.GetMapping(sourceNodeClass.ClassName);
-        var targetClassGuid = sourceNodeClass.ClassGUID;
-        var targetClassInfo = DataClassInfoProvider.ProviderObject.Get(sourceNodeClass.ClassName);
-        if (mapping is not null)
+
+        var formerUrlPaths = GetFormerUrlPaths(cmsTree);
+        var directive = GetDirective(new ContentItemSource(cmsTree, sourceNodeClass.ClassName, mapping?.TargetClassName ?? sourceNodeClass.ClassName, sourceSite, formerUrlPaths, childNodes));
+
+        if (directive is DropDirective)
         {
-            targetClassInfo = DataClassInfoProvider.ProviderObject.Get(mapping.TargetClassName) ?? throw new InvalidOperationException($"Unable to find target class '{mapping.TargetClassName}'");
-            targetClassGuid = targetClassInfo.ClassGUID;
+            logger.LogInformation("Content item skipped. Reason: {Reason} NodeGUID: {NodeGUID} NodeAliasPath: {NodeAliasPath}", "Explicit drop directive", cmsTree.NodeGUID, cmsTree.NodeAliasPath);
+            yield break;
         }
 
+        string targetClassName = directive.TargetTypeOverride ?? mapping?.TargetClassName ?? sourceNodeClass.ClassName;
+        var targetClassInfo = DataClassInfoProvider.ProviderObject.Get(targetClassName);
         bool migratedAsContentFolder = sourceNodeClass.ClassName.Equals("cms.folder", StringComparison.InvariantCultureIgnoreCase) && !configuration.UseDeprecatedFolderPageType.GetValueOrDefault(false);
 
         if (targetClassInfo is null && !migratedAsContentFolder)
         {
-            logger.LogError("Could not map content item. Target class DataClassInfo ClassGUID={ClassGUID} not found.", targetClassGuid);
+            logger.LogError("Could not map source node NodeGUID={NodeGuid}. Target class with name {ClassName} was not identified in target instance.", cmsTree.NodeGUID, targetClassName);
             yield break;
         }
 
         var contentItemGuid = spoiledGuidContext.EnsureNodeGuid(cmsTree.NodeGUID, cmsTree.NodeSiteID, cmsTree.NodeID);
 
-        var formerUrlPaths = GetFormerUrlPaths(cmsTree);
-
-        var directive = GetDirective(new ContentItemSource(cmsTree, sourceNodeClass.ClassName, mapping?.TargetClassName ?? sourceNodeClass.ClassName, sourceSite, formerUrlPaths, childNodes));
         directive.ContentItemGuid = contentItemGuid;
         directive.TargetClassInfo = targetClassInfo;
         directive.Node = cmsTree;
         yield return directive;
 
-        if (directive is DropDirective)
-        {
-            logger.LogInformation("Content item skipped. Reason: {Explicit drop directive} NodeGUID: {NodeGUID} NodeAliasPath: {NodeAliasPath}", "Explicit drop directive", cmsTree.NodeGUID, cmsTree.NodeAliasPath);
-            yield break;
-        }
-        else if (directive is ConvertToWidgetDirective && cmsTree.NodeHasChildren == true && !deferred)
+        if (directive is ConvertToWidgetDirective && cmsTree.NodeHasChildren == true && !deferred)
         {
             deferredTreeNodesService.AddNode(cmsTree);
             yield break;
         }
 
-
         bool isMappedTypeReusable = targetClassInfo?.ClassContentTypeType is ClassContentTypeType.REUSABLE || configuration.ClassNamesConvertToContentHub.Contains(sourceNodeClass.ClassName);
         if (isMappedTypeReusable)
         {
@@ -153,7 +147,7 @@ protected override IEnumerable<IUmtModel> MapInternal(CmsTreeMapperSource source
             ContentItemName = safeNodeName,
             ContentItemIsReusable = isMappedTypeReusable,
             ContentItemIsSecured = cmsTree.IsSecuredNode ?? false,
-            ContentItemDataClassGuid = migratedAsContentFolder ? null : targetClassGuid,
+            ContentItemDataClassGuid = migratedAsContentFolder ? null : targetClassInfo!.ClassGUID,
             ContentItemChannelGuid = isMappedTypeReusable ? null : siteGuid,
             ContentItemContentFolderGUID = contentFolderGuid,
             ContentItemWorkspaceGUID = workspaceGuid
@@ -200,7 +194,7 @@ protected override IEnumerable<IUmtModel> MapInternal(CmsTreeMapperSource source
                 List<IUmtModel>? migratedDraft = null;
                 try
                 {
-                    migratedDraft = MigrateDraft(draftVersion, cmsTree, sourceFormDefinition, targetFormDefinition!, contentItemGuid, languageGuid, sourceNodeClass, websiteChannelInfo, sourceSite, mapping).ToList();
+                    migratedDraft = MigrateDraft(draftVersion, cmsTree, sourceFormDefinition, targetClassInfo!.ClassFormDefinition, contentItemGuid, languageGuid, sourceNodeClass, websiteChannelInfo, sourceSite, mapping).ToList();
                     draftMigrated = true;
                 }
                 catch
@@ -325,9 +319,9 @@ protected override IEnumerable<IUmtModel> MapInternal(CmsTreeMapperSource source
 
             if (!migratedAsContentFolder)
             {
-                var dataModel = new ContentItemDataModel { ContentItemDataGUID = commonDataModel.ContentItemCommonDataGUID, ContentItemDataCommonDataGuid = commonDataModel.ContentItemCommonDataGUID, ContentItemContentTypeName = mapping?.TargetClassName ?? sourceNodeClass.ClassName };
+                var dataModel = new ContentItemDataModel { ContentItemDataGUID = commonDataModel.ContentItemCommonDataGUID, ContentItemDataCommonDataGuid = commonDataModel.ContentItemCommonDataGUID, ContentItemContentTypeName = targetClassInfo!.ClassName };
 
-                var fi = new FormInfo(targetFormDefinition);
+                var fi = new FormInfo(targetClassInfo!.ClassFormDefinition);
 
                 var includedMetadata = configuration.IncludeExtendedMetadata.GetValueOrDefault(false) ? IncludedMetadata.Extended : IncludedMetadata.Basic;
                 FormFieldInfo[] commonFields = UnpackReusableFieldSchemas(fi.GetFields<FormSchemaInfo>()).ToArray();
@@ -358,8 +352,6 @@ protected override IEnumerable<IUmtModel> MapInternal(CmsTreeMapperSource source
                     }
                 }
 
-                string targetClassName = mapping?.TargetClassName ?? sourceNodeClass.ClassName;
-
                 // Map legacy metadata fields
                 // Fields from custom class mapping
                 if (mapping is not null)
@@ -915,7 +907,7 @@ string targetClassName
                     {
                         // relation to other document
                         var convertedRelation = relationshipService.GetNodeRelationships(documentSourceObjectContext.CmsTree.NodeID, sourceNodeClass.ClassName, field.Guid)
-                            .Select(r => new WebPageRelatedItem { WebPageGuid = spoiledGuidContext.EnsureNodeGuid(r.RightNode!.NodeGUID, r.RightNode.NodeSiteID, r.RightNode.NodeID) });
+                            .Select(r => new { Identifier = spoiledGuidContext.EnsureNodeGuid(r.RightNode!.NodeGUID, r.RightNode.NodeSiteID, r.RightNode.NodeID) });
 
                         target.SetValueAsJson(targetFieldName, valueConvertor.Invoke(convertedRelation, convertorContext));
                     }
diff --git a/KVA/Migration.Tool.Source/Mappers/ContentItemMapperDirectives/ContentItemActionProvider.cs b/KVA/Migration.Tool.Source/Mappers/ContentItemMapperDirectives/ContentItemActionProvider.cs
@@ -35,4 +35,5 @@ public void LinkChildren(string fieldName, IEnumerable<ICmsTree> children)
             Directive.ChildLinks.Add((fieldName, child));
         }
     }
+    public void OverrideTargetType(string targetType) => Directive.TargetTypeOverride = targetType;
 }
diff --git a/KVA/Migration.Tool.Source/Mappers/ContentItemMapperDirectives/ContentItemDirectiveBase.cs b/KVA/Migration.Tool.Source/Mappers/ContentItemMapperDirectives/ContentItemDirectiveBase.cs
@@ -14,6 +14,7 @@ internal abstract class ContentItemDirectiveBase : IUmtModel
     public bool RegenerateUrlPath { get; set; } = false;
     public IEnumerable<FormerPageUrlPath>? FormerUrlPaths { get; set; }
     public List<(string fieldName, ICmsTree)> ChildLinks { get; set; } = [];
+    public string? TargetTypeOverride { get; set; }
 
     #region Mapping results, used for postprocessing
     public Guid ContentItemGuid { get; set; }
diff --git a/KVA/Migration.Tool.Source/Mappers/ContentItemMapperDirectives/IContentItemActionProvider.cs b/KVA/Migration.Tool.Source/Mappers/ContentItemMapperDirectives/IContentItemActionProvider.cs
@@ -26,6 +26,12 @@ public interface IContentItemActionProvider : IBaseContentItemActionProvider
     /// <param name="fieldName">Name of the field to add the child content item references to</param>
     /// <param name="children">One or more child objects passed by <see cref="ContentItemSource.ChildNodes"/></param>
     void LinkChildren(string fieldName, IEnumerable<ICmsTree> children);
+
+    /// <summary>
+    /// Instructs Migration Tool to map the source page to a specific content type on XbyK side.
+    /// </summary>
+    /// <param name="targetTypeName">Class name of the target content type (ClassName of CMS_Class table)</param>
+    void OverrideTargetType(string targetTypeName);
 }
 
 public record FormerPageUrlPath(string LanguageName, string Path, DateTime? LastModified = null);
diff --git a/Migration.Tool.Common/Builders/ClassMapper.cs b/Migration.Tool.Common/Builders/ClassMapper.cs
@@ -40,9 +40,9 @@ public record FieldMapping(string TargetFieldName, string SourceClassName, strin
 
 public record FieldMappingWithConversion(string TargetFieldName, string SourceClassName, string SourceFieldName, bool IsTemplate, Func<object?, IConvertorContext, object?> Converter) : IFieldMapping;
 
-public class MultiClassMapping(string targetClassName, Action<DataClassInfo> classPatcher) : IClassMapping
+public class MultiClassMapping(string targetClassName, Action<DataClassInfo> classPatcher = null) : IClassMapping
 {
-    public void PatchTargetDataClass(DataClassInfo target) => classPatcher(target);
+    public void PatchTargetDataClass(DataClassInfo target) => classPatcher?.Invoke(target);
 
     ICollection<string> IClassMapping.SourceClassNames => SourceClassNames;
     IList<IFieldMapping> IClassMapping.Mappings => Mappings;
diff --git a/Migration.Tool.Extensions/ClassMappings/ClassMappingSample.cs b/Migration.Tool.Extensions/ClassMappings/ClassMappingSample.cs
@@ -541,4 +541,56 @@ public static IServiceCollection AddReusableSchemaAutoGenerationSample(this ISer
 
         return serviceCollection;
     }
+
+    public static IServiceCollection AddMappingToPrefabricatedContentTypeSample(this IServiceCollection serviceCollection)
+    {
+        // Summary:
+        //   This sample shows how to migrate pages to a content type that is already present in the target instance
+        //   - i.e., not created by the --page-types command.
+        //
+        // Prerequisites:
+        //   1. CLI is invoked with --bypass-dependency-check argument and without --page-types argument.
+        //
+        //   2. The following structures already exist in the target XbyK instance. They might have been created by MT,
+        //      manually in XbyK administration or by other means.
+        //          A. Reusable field schema PrefabBase
+        //          B. Content type DancingGoatCore.PrefabArticle that uses PrefabBase. It can be of both reusable and page usage.
+        //          C. In case of migrating media to content hub, Legacy Media File content type must exist
+        //             and match AssetFacade.LegacyMediaFileContentType class name and class GUID. See PrefabArticleTeaser below.
+        //
+        //   3. Field types in the target structures must be compatible with source field types - i.e., Migration Tool must support
+        //      migration from one to the other.
+        //
+        //      If you're unsure what the target field type should be, let MT migrate page types (--page-types CLI command)
+        //      into a disposable clone of your target instance and see the produced field types.
+
+        var m = new MultiClassMapping("DancingGoatCore.PrefabArticle");
+        const string sourceClassName = "DancingGoatCore.Article";
+
+        // Field mapping
+        m.BuildField("PrefabArticleSummary")
+            .SetFrom(sourceClassName, "ArticleSummary");
+
+        // For media file mapping, make sure the target field supports the media file migration strategy 
+        // set by appsettings MigrateMediaToMediaLibrary.
+        //   - MigrateMediaToMediaLibrary=true -> target field data type = 'Media files'
+        //   - MigrateMediaToMediaLibrary=false -> target field data type = 'Pages and reusable content'
+        //     and allowed content types must include Legacy Media File content type. See AssetFacade.LegacyMediaFileContentType
+        m.BuildField("PrefabArticleTeaser")
+            .SetFrom(sourceClassName, "ArticleTeaser");
+
+        // For linked items mapping, make sure the target field has 'Pages and reusable content' data type
+        // and allowed content types include the content type of linked items. What this linked content type actually is
+        // depends on your specific setup (custom class mapping, content item directors, etc.).
+        m.BuildField("PrefabArticleRelatedArticles")
+            .SetFrom(sourceClassName, "ArticleRelatedArticles");
+
+        // Reusable field schema field mapping
+        m.UseResusableSchema("PrefabBase");
+        m.BuildField("PrefabBaseTitle")
+            .SetFrom(sourceClassName, "ArticleTitle");
+
+        serviceCollection.AddSingleton<IClassMapping>(m);
+        return serviceCollection;
+    }
 }
diff --git a/Migration.Tool.Extensions/CommunityMigrations/JsonBasedTypeRemapDirector.cs b/Migration.Tool.Extensions/CommunityMigrations/JsonBasedTypeRemapDirector.cs
@@ -0,0 +1,55 @@
+﻿using System.Text.Json;
+using Migration.Tool.Source.Mappers.ContentItemMapperDirectives;
+
+namespace Migration.Tool.Extensions.CommunityMigrations;
+
+/// <summary>
+/// This content item director overrides target content type based on class name of the source page.
+/// The override logic is driven by a JSON file. Unspecified source classes are not affected.
+/// </summary>
+/// <remarks>
+/// JSON file example:
+/// {
+///     "mapping": {
+///         "contentTypes": {
+///             "DancingGoatCore.Article": "NewProjectNamespace.PrefabricatedArticleType",
+///             "DancingGoatCore.Product": "NewProjectNamespace.PrefabricatedProductType"
+///         }
+///     }
+/// }
+/// </remarks>
+public class JsonBasedTypeRemapDirector : ContentItemDirectorBase
+{
+    private readonly Dictionary<string, string> definitions;
+
+    public JsonBasedTypeRemapDirector(string jsonFilePath)
+    {
+        if (string.IsNullOrWhiteSpace(jsonFilePath))
+        {
+            throw new ArgumentException("JSON file path cannot be null or empty", nameof(jsonFilePath));
+        }
+
+        var jsonContent = File.ReadAllText(jsonFilePath);
+        var mappingData = JsonSerializer.Deserialize<MappingDefinitions>(jsonContent, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
+
+        definitions = mappingData?.Mapping?.ContentTypes ?? throw new InvalidOperationException("Invalid JSON structure. Expected 'mapping.contentTypes'.");
+    }
+
+    public override void Direct(ContentItemSource source, IContentItemActionProvider options)
+    {
+        if (definitions.TryGetValue(source.SourceClassName, out var targetTypeName))
+        {
+            options.OverrideTargetType(targetTypeName);
+        }
+    }
+
+    private class MappingDefinitions
+    {
+        public MappingData? Mapping { get; set; }
+
+        public class MappingData
+        {
+            public Dictionary<string, string>? ContentTypes { get; set; }
+        }
+    }
+}
diff --git a/Migration.Tool.Extensions/ServiceCollectionExtensions.cs b/Migration.Tool.Extensions/ServiceCollectionExtensions.cs
@@ -25,6 +25,20 @@ public static IServiceCollection UseCustomizations(this IServiceCollection servi
         // services.AddReusableSchemaAutoGenerationSample();
         // services.AddTransient<ContentItemDirectorBase, SamplePageToWidgetDirector>();
         // services.AddTransient<ContentItemDirectorBase, SampleChildLinkDirector>();
+
+        // Routing content items to prefabricated content types (i.e., types not created by Migration Tool --page-types CLI argument)
+        //
+        // The following two methods may be combined, but one particular content type should be covered by only one of them.
+        //
+        //   1. Content item director method is applicable if each target field has a matching source field that has the same name.
+        //      You may use JsonBasedTypeRemapDirector or drive the mapping directly from your own director using IContentItemActionProvider.OverrideTargetType method.
+        //
+        //      services.AddTransient<ContentItemDirectorBase>(sp => new JsonBasedTypeRemapDirector("migration-mapping.json"));
+        //
+        //   2. Custom mapping method gives you the highest flexibility if the prefabricated type doesn't match the source type exactly.
+        //
+        //      services.AddMappingToPrefabricatedContentTypeSample();
+
         return services;
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -35,4 +35,5 @@ public void LinkChildren(string fieldName, IEnumerable<ICmsTree> children)`
`35`	`35`	`Directive.ChildLinks.Add((fieldName, child));`
`36`	`36`	`}`
`37`	`37`	`}`
	`38`	`+ public void OverrideTargetType(string targetType) => Directive.TargetTypeOverride = targetType;`
`38`	`39`	`}`
Original file line number	Diff line number	Diff line change
`@@ -40,9 +40,9 @@ public record FieldMapping(string TargetFieldName, string SourceClassName, strin`
`40`	`40`
`41`	`41`	`public record FieldMappingWithConversion(string TargetFieldName, string SourceClassName, string SourceFieldName, bool IsTemplate, Func<object?, IConvertorContext, object?> Converter) : IFieldMapping;`
`42`	`42`
`43`		`-public class MultiClassMapping(string targetClassName, Action<DataClassInfo> classPatcher) : IClassMapping`
	`43`	`+public class MultiClassMapping(string targetClassName, Action<DataClassInfo> classPatcher = null) : IClassMapping`
`44`	`44`	`{`
`45`		`- public void PatchTargetDataClass(DataClassInfo target) => classPatcher(target);`
	`45`	`+ public void PatchTargetDataClass(DataClassInfo target) => classPatcher?.Invoke(target);`
`46`	`46`
`47`	`47`	`ICollection<string> IClassMapping.SourceClassNames => SourceClassNames;`
`48`	`48`	`IList<IFieldMapping> IClassMapping.Mappings => Mappings;`