Merge pull request #540 from Kentico/develop

akfakmot · web-flow · commit 3d61aba97bb2 · 2025-11-07T16:34:40.000+01:00
Release 3.19.0
diff --git a/KVA/Migration.Tool.Source/Providers/ClassMappingProvider.cs b/KVA/Migration.Tool.Source/Providers/ClassMappingProvider.cs
@@ -313,12 +313,14 @@ private void ExecReusableSchemaBuilders()
                             patcher.RemoveCategories();
 
                             var fi = new FormInfo(patcher.GetPatched());
-                            return fi.GetFormField(fieldIdentifier.FieldName) switch
+                            var patchedFieldInfo = fi.GetFormField(fieldIdentifier.FieldName) switch
                             {
                                 { } field => field,
                                 _ => throw new InvalidOperationException(
                                     $"Invalid reusable schema field builder for field '{fieldIdentifier.ClassName}': Class '{fieldIdentifier.ClassName}' is missing field '{fieldIdentifier.FieldName}'")
                             };
+                            patchedFieldInfo.Name = fb.TargetFieldName;
+                            return patchedFieldInfo;
                         }
                         default:
                         {
diff --git a/Migration.Tool.CLI/README.md b/Migration.Tool.CLI/README.md
@@ -169,19 +169,22 @@ Pages from older product versions can be migrated to either to [website channel
 - Linked pages are currently not supported in Xperience by Kentico. By default, the migration creates standard page copies for any
   linked pages on the source instance. This behavior can be changed by implementing [custom handling of linked pages](../Migration.Tool.Extensions/README.md#customize-linked-page-handling).
 - Page permissions (ACLs) are currently not migrated into Xperience by Kentico.
-- Migration of page builder content is only available for Kentico Xperience 13.
+- Migration of Page Builder content is only available for Kentico Xperience 13.
 
 Additionally, you can define [custom migrations](../Migration.Tool.Extensions/README.md) to change the default behavior, for example to migrate page content to widgets in Xperience by Kentico.
 
-#### Page builder content
+#### Page Builder content
 
-> :warning: Page builder content migration is only available when migrating from Kentico Xperience 13.
+> :warning: Page Builder content migration is only available when migrating from Kentico Xperience 13.
 
-By default, JSON data storing the page builder content of pages and custom page templates is migrated directly without
+By default, JSON data storing the Page Builder content of pages and custom page templates is migrated directly without
 modifications. On the target Xperience by Kentico instance, the migrated data can work in the Page Builder's legacy
 compatibility mode. However, we strongly recommend updating your codebase to the new Xperience by Kentico components.
 
-The Kentico Migration Tool provides an advanced migration mode for page builder content that utilizes API discovery on
+> [!TIP]
+> Read more about different [approaches of migrating Page Builder content](https://docs.kentico.com/x/migrate_widgets_from_KX13_guides) and their the pros and cons in our documentation. 
+
+The Kentico Migration Tool provides an advanced migration mode for Page Builder content that utilizes API discovery on
 the source instance. To learn more details and how to configure this feature,
 see [Source instance API discovery](#source-instance-api-discovery).
 
@@ -441,7 +444,7 @@ Add the options under the `Settings` section in the configuration file.
 | EntityConfigurations._&lt;object table name&gt;_.ExcludeCodeNames | Excludes objects with the specified code names from the migration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | CreateReusableFieldSchemaForClasses                               | Specifies which page types are also converted to [reusable field schemas](#convert-page-types-to-reusable-field-schemas). This option cannot be combined with usage of `ReusableSchemaBuilder` in [custom class mappings](../Migration.Tool.Extensions/README.md#custom-class-mappings).                                                                                                                                                                                                                                                                   
                                                                                                                                                                                                                                                                                                                                |
-| OptInFeatures.QuerySourceInstanceApi.Enabled                      | If `true`, [source instance API discovery](#source-instance-api-discovery) is enabled to allow advanced migration of page builder content for pages and page templates.                                                                                                                                                                                                                                                                                                                                                                                    |
+| OptInFeatures.QuerySourceInstanceApi.Enabled                      | If `true`, [source instance API discovery](#source-instance-api-discovery) is enabled to allow advanced migration of Page Builder content for pages and page templates.                                                                                                                                                                                                                                                                                                                                                                                    |
 | OptInFeatures.QuerySourceInstanceApi.Connections                  | To use [source instance API discovery](#source-instance-api-discovery), you need to add a connection JSON object containing the following values:<br />`SourceInstanceUri` - the base URI where the source instance's live site application is running.<br />`Secret` - the secret that you set in the _ToolkitApiController.cs_ file on the source instance.                                                                                                                                                                                              |
 | OptInFeatures.CustomMigration.FieldMigrations                     | Enables conversion of media selection text fields to content item assets or media library files. See [Convert text fields with media links](#convert-text-fields-with-media-links) for more information.                                                                                                                                                                                                                                                                                                                                                   |
 
@@ -531,16 +534,16 @@ Add the options under the `Settings` section in the configuration file.
 
 > :warning: **Warning** – source instance API discovery is only available when migrating from Kentico Xperience 13.
 
-By default, JSON data storing the page builder content of pages and custom page templates is migrated directly without
-modifications. Within this content, page builder components (widgets, sections, etc.) with properties have their
+By default, JSON data storing the Page Builder content of pages and custom page templates is migrated directly without
+modifications. Within this content, Page Builder components (widgets, sections, etc.) with properties have their
 configuration based on Kentico Xperience 13 form components, which are assigned to the properties on the source
 instance. On the target Xperience by Kentico instance, the migrated data can work in the Page Builder's legacy
 compatibility mode.
 
 However, we strongly recommend updating your codebase to the new Xperience by Kentico components.
 See [Editing components in Xperience by Kentico](https://docs.xperience.io/x/wIfWCQ) to learn more.
 
-To convert page builder data to a format suitable for the Xperience by Kentico components, the Kentico Migration Tool
+To convert Page Builder data to a format suitable for the Xperience by Kentico components, the Kentico Migration Tool
 provides an advanced migration mode that utilizes API discovery on the source instance. The advanced mode currently
 provides the following data conversion:
 
@@ -553,8 +556,8 @@ provides the following data conversion:
 
 - To use source instance API discovery, the live site application of your source instance must be running and available
   during the migration.
-- Using the advanced page builder data migration **prevents the data from being used in the Page Builder's legacy
-  compatibility mode**. With this approach, you need to update all page builder component code files to
+- Using the advanced Page Builder data migration **prevents the data from being used in the Page Builder's legacy
+  compatibility mode**. With this approach, you need to update all Page Builder component code files to
   the [Xperience by Kentico format](https://docs.xperience.io/x/wIfWCQ).
 - The source instance API discovery feature only processes component properties defined using `[EditingComponent]`
   attribute notation. Other implementations, such as properties edited via custom view components in the Razer view, are
@@ -647,8 +650,8 @@ You can test the source instance API discovery by making a POST request
 to `<source instance live site URI>/ToolApi/Test` with `{ "secret":"__your secret string__" }` in the body. If your
 setup is correct, the response should be: `{ "pong": true }`
 
-When you now [migrate data](#migrate-data), the tool performs API discovery of page builder component code on the source
-instance and advanced migration of page builder data.
+When you now [migrate data](#migrate-data), the tool performs API discovery of Page Builder component code on the source
+instance and advanced migration of Page Builder data.
 
 ## Convert pages or custom tables to Content hub
 
diff --git a/Migration.Tool.Extensions/README.md b/Migration.Tool.Extensions/README.md
@@ -154,6 +154,9 @@ You can see a sample: [SampleWidgetMigration.cs](./CommunityMigrations/SampleWid
 
 After implementing the migration, you need to [register the migration](#register-migrations) in the system.
 
+> [!TIP]
+> For a complete end-to-end example, see our guide on [how to migrate widget data as reusable content](https://docs.kentico.com/x/migrate_widget_data_as_reusable_content_guides) in the Kentico documentation.
+
 ## Customize widget property migrations
 
 In the `Migration.Tool.Extensions/CommunityMigrations` folder, create a new file with a class that implements the `IWidgetPropertyMigration` interface. Implement the following properties and methods required by the interface:
@@ -176,6 +179,9 @@ You can see samples:
 
 After implementing the migration, you need to [register the migration](#register-migrations) in the system.
 
+> [!TIP]
+> For common widget property transformation scenarios, see [our technical deep-dive guide](https://docs.kentico.com/x/transform_widget_properties_guides) in the Kentico documentation.
+
 ## Migrate pages to widgets
 
 This migration allows you to migrate pages from the source instance as [widgets](https://docs.kentico.com/x/7gWiCQ) in the target instance. This migration can be used in the following ways:
@@ -239,6 +245,9 @@ You can see a sample: [SamplePageToWidgetDirector.cs](./CommunityMigrations/Samp
 
 After implementing the content item director, you need to [register the director](#register-migrations) in the system.
 
+> [!TIP]
+> For a complete practical example, see [how to convert child pages to widgets](https://docs.kentico.com/x/convert_child_pages_to_widgets_guides) in the Kentico documentation.
+
 ## Register migrations
 
 Register the migration in `Migration.Tool.Extensions/ServiceCollectionExtensions.cs` as a `Transient` dependency into the service collection:

Original file line number	Diff line number	Diff line change
`@@ -313,12 +313,14 @@ private void ExecReusableSchemaBuilders()`
`313`	`313`	`patcher.RemoveCategories();`
`314`	`314`
`315`	`315`	`var fi = new FormInfo(patcher.GetPatched());`
`316`		`- return fi.GetFormField(fieldIdentifier.FieldName) switch`
	`316`	`+ var patchedFieldInfo = fi.GetFormField(fieldIdentifier.FieldName) switch`
`317`	`317`	`{`
`318`	`318`	`{ } field => field,`
`319`	`319`	`_ => throw new InvalidOperationException(`
`320`	`320`	`$"Invalid reusable schema field builder for field '{fieldIdentifier.ClassName}': Class '{fieldIdentifier.ClassName}' is missing field '{fieldIdentifier.FieldName}'")`
`321`	`321`	`};`
	`322`	`+ patchedFieldInfo.Name = fb.TargetFieldName;`
	`323`	`+ return patchedFieldInfo;`
`322`	`324`	`}`
`323`	`325`	`default:`
`324`	`326`	`{`