Skip to content

Commit f55343a

Browse files
DavidBKenticoDavidBKentico
committed
Module class content hub migration documentation review
1 parent 01fa0ab commit f55343a

File tree

3 files changed

+34
-22
lines changed

3 files changed

+34
-22
lines changed

‎Migration.Tool.CLI/README.md‎

Lines changed: 31 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,8 @@ Module and class migration does NOT include:
248248
see [Role management](https://docs.xperience.io/x/7IVwCg)
249249
and [UI page permission checks](https://docs.xperience.io/x/8IKyCg))
250250

251+
Custom module classes and the stored data records are either migrated as module classes in Xperience by Kentico (default behavior) or [reusable content items](https://docs.kentico.com/x/content_items_xp) in Content hub. See [Convert module classes to Content hub](#convert-module-classes-to-content-hub) for detailed information.
252+
251253
As with all object types, the Kentico Migration Tool does not transfer code files to the target project. You need to
252254
manually move all code files generated for your custom classes (_Info_, _InfoProvider_, etc.).
253255

@@ -416,7 +418,8 @@ Add the options under the `Settings` section in the configuration file.
416418
| XbyKDirPath | The absolute file system path of the root of the target Xperience by Kentico project. Required to migrate media library and page attachment files. |
417419
| XbyKApiSettings | Configuration options set for the API when creating migrated objects in the target application.<br /><br />The `ConnectionStrings.CMSConnectionString`option is required - set the connection string to the target Xperience by Kentico database (the same value as obsolete `XbKConnectionString`). |
418420
| MigrationProtocolPath | The absolute file system path of the location where the [migration protocol file](./MIGRATION_PROTOCOL_REFERENCE.md) is generated.<br /><br />For example: `"C:\\Logs\\Migration.Tool.Protocol.log"` |
419-
| ConvertClassesToContentHub | Specifies which page types, custom tables or custom module classes (see [custom module classes migration](#custom-module-classes-migration)) are migrated to [reusable content items](https://docs.kentico.com/x/content_items_xp) (instead of website channel pages or custom module classes for custom tables). Enter page type code names, separated with either `;` or `,`. See [Convert pages or custom tables to Content hub](#convert-pages-or-custom-tables-to-content-hub) for detailed information. |
421+
| ConvertClassesToContentHub | Specifies which page types, custom tables or custom module classes are migrated to [reusable content items](https://docs.kentico.com/x/content_items_xp) (instead of website channel pages or custom module classes for custom tables and classes). Enter page type code names, separated with either `;` or `,`. See [Convert pages or custom tables to Content hub](#convert-pages-or-custom-tables-to-content-hub) or [Convert module classes to Content hub](#convert-module-classes-to-content-hub) for detailed information. |
422+
| CustomModuleClassDisplayNamePatterns | Specifies the format of content item names for items migrated from custom module classes. Add a dictionary with the class name as the key and the name pattern as the value. The name pattern can use placeholders that are replaced by values from a specific column in the source class. <br /><br />Example: `CustomModuleItem-{CustomClassGuid}` |
420423
| MigrateOnlyMediaFileInfo | If set to `true`, only the database representations of media files are migrated, without the files in the media folder in the project's file system. For example, enable this option if your media library files are mapped to a shared directory or Cloud storage.<br /><br />If `false`, media files are migrated based on the `KxCmsDirPath` location. |
421424
| MigrateMediaToMediaLibrary | Determines whether media library files and attachments from the source instance are migrated to the target instance as media libraries or as [content item assets](https://docs.kentico.com/x/content_item_assets_xp) in the content hub. The default value is `false` – media files and attachments are migrated as content item assets. <br /><br /> See [Convert attachments and media library files to media libraries instead of content item assets](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) |
422425
| LegacyFlatAssetTree | Use legacy behavior of versions up to 2.3.0. Content folders for asset content items will be created in a flat structure (all under root folder) |
@@ -428,7 +431,6 @@ Add the options under the `Settings` section in the configuration file.
428431
| EntityConfigurations | Contains options that allow you to fine-tune the migration of specific object types. |
429432
| EntityConfigurations._&lt;object table name&gt;_.ExcludeCodeNames | Excludes objects with the specified code names from the migration. |
430433
| CreateReusableFieldSchemaForClasses | Specifies which page types are also converted to [reusable field schemas](#convert-page-types-to-reusable-field-schemas). |
431-
| CustomModuleClassDisplayNamePatterns | Specifies content item display name for custom module classes converted to reusable content item. It's a dictionary with class name as a key and pattern as a value. Your pattern can use placeholders for the source class columns.<br />Example: `CustomModuleItem-{CustomModuleGuid}`
432434
| 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. |
433435
| 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. |
434436
| 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. |
@@ -461,7 +463,10 @@ Add the options under the `Settings` section in the configuration file.
461463
},
462464
"MigrationProtocolPath": "C:\\_Development\\xperience-migration-toolkit-master\\Migration.Tool.Protocol.log",
463465
"MemberIncludeUserSystemFields": "FirstName|MiddleName|LastName|FullName|UserPrivilegeLevel|UserIsExternal|LastLogon|UserLastModified|UserGender|UserDateOfBirth",
464-
"ConvertClassesToContentHub": "Acme.Article,Acme.Product",
466+
"ConvertClassesToContentHub": "Acme.Article,Acme.Product,Acme.CustomClass",
467+
"CustomModuleClassDisplayNamePatterns": {
468+
"Acme.CustomClass": "Item-{CustomClassGuid}"
469+
},
465470
"MigrateOnlyMediaFileInfo": false,
466471
"MigrateMediaToMediaLibrary": false,
467472
"UseOmActivityNodeRelationAutofix": "AttemptFix",
@@ -506,9 +511,6 @@ Add the options under the `Settings` section in the configuration file.
506511
"Actions": ["convert to asset"],
507512
"FieldNameRegex": ".*"
508513
}
509-
},
510-
"CustomModuleClassDisplayNamePatterns": {
511-
"Module1.CustomClass1": "Item-{CustomClass1Guid}"
512514
}
513515
}
514516
}
@@ -657,7 +659,28 @@ The migration then converts the specified page types or custom tables to content
657659

658660
For advanced scenarios, you can use the extensibility feature to implement [customizations](../Migration.Tool.Extensions/README.md#custom-class-mappings) that map specific page types, custom tables or their individual fields to reusable content types. For example, this allows you to migrate multiple page types to a single content type.
659661

660-
To preserve relationship between page converted to reusable content item and its children, you can use [Custom child links](../Migration.Tool.Extensions/README.md#custom-child-links). This feature allows you to map children of the original page to a content item/page selector field of the target reusable content item.
662+
To preserve relationships between pages converted to reusable content items and its children, you can use [Custom child links](../Migration.Tool.Extensions/README.md#custom-child-links). This feature allows you to map children of the original page to a content item/page selector field of the target reusable content item.
663+
664+
## Convert module classes to Content hub
665+
666+
**Note**: This feature is only tested only when using Kentico Xperience 13 as the migration source.
667+
668+
You can migrate custom module classes and their data records to [Content hub items](https://docs.kentico.com/x/content_items_xp) instead of modules classes.
669+
670+
Specify a list of module class code names (separated with either `;` or `,`) in the `Settings.ConvertClassesToContentHub` [configuration option](#configuration). Optionally, you can specify the name pattern for the migrated content items using the `Settings.CustomModuleClassDisplayNamePatterns` option.
671+
672+
```json
673+
"Settings":{
674+
...
675+
676+
"ConvertClassesToContentHub": "Acme.Article,Acme.Product,Acme.CustomClass",
677+
"CustomModuleClassDisplayNamePatterns": {
678+
"Acme.CustomClass": "Item-{CustomClassGuid}"
679+
},
680+
```
681+
682+
For advanced scenarios, you can use the extensibility feature to implement [customizations](../Migration.Tool.Extensions/README.md#custom-class-mappings) that map specific module classes or their individual fields to reusable content types. For example, this allows you to migrate multiple classes to a single content type.
683+
661684
## Convert page types to reusable field schemas
662685

663686
It is not possible to migrate any page types that inherit fields from other page types. However, to make the manual
@@ -806,16 +829,4 @@ Additionally, any attachments placed into the content of migrated pages **will n
806829
This includes images and file download links that use **/getattachment** and **/getimage** URLs.
807830

808831
If you wish to continue using these legacy attachment URLs from earlier product versions, you need to add a custom
809-
handler to your Xperience by Kentico project.
810-
See [`Migration.Tool.KXP.Extensions/README.MD`](/Migration.Tool.KXP.Extensions/README.MD) for instructions.
811-
812-
## Custom module classes migration
813-
814-
Items of custom module classes can be migrated to reusable content items. You may also apply custom class mapping extension.
815-
816-
**Note that this feature is tested only for Kentico 13 version of source instance.**
817-
818-
To achieve migration to reusable content items:
819-
1. Specify the module's class name(s) in ConvertClassesToContentHub appsettings list
820-
2. *Optional:* Specify display name pattern using CustomModuleClassDisplayNamePatterns appsettings configuration key
821-
2. *Optional:* Register custom mapping. See [`Migration.Tool.KXP.Extensions/README.MD`](/Migration.Tool.KXP.Extensions/README.MD) for instructions.
832+
handler to your Xperience by Kentico project. See [`Migration.Tool.KXP.Extensions/README.MD`](/Migration.Tool.KXP.Extensions/README.MD) for instructions.

‎Migration.Tool.Extensions/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -229,7 +229,7 @@ You can customize class mappings to adjust the content model between the source
229229

230230
8. Ensure that your class mapping extension methods run during the startup of the migration tool. Call the methods from `UseCustomizations` in the [ServiceCollectionExtensions](/Migration.Tool.Extensions/ServiceCollectionExtensions.cs) class.
231231

232-
**Note**: Your mappings now replace the default migration functionality for all data classes (page types or custom tables) that you use as a source. Any class where you set at least one source field is affected. If you map only some fields from a source class, the remaining fields are not migrated at all.
232+
**Note**: Your mappings now replace the default migration functionality for all data classes (page types, custom tables or custom module classes) that you use as a source. Any class where you set at least one source field is affected. If you map only some fields from a source class, the remaining fields are not migrated at all.
233233

234234
### Examples
235235

‎docs/Supported-Data.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Currently, the Kentico Migration Tool supports the following types of data:
2121
- However, you can create [reusable field schemas](../Migration.Tool.CLI/README.md#convert-page-types-to-reusable-field-schemas) for page types from which other page types inherit.
2222
- All migrated Content types have the **Include in routing** option enabled (the migration never creates pages without URL and routing).
2323
- **Pages**
24-
- Pages can be migrated to either to [website channel pages](https://docs.kentico.com/x/JwKQC) (default behavior) or [reusable content items](https://docs.kentico.com/x/barWCQ) in Content hub.
24+
- Pages can be migrated either to [website channel pages](https://docs.kentico.com/x/JwKQC) (default behavior) or [reusable content items](https://docs.kentico.com/x/barWCQ) in Content hub.
2525
- The migration includes the following versions of pages:
2626
- _Published_
2727
- _Latest draft version_ - for published pages, the version is migrated to the _Draft (New version)_ [status](https://docs.kentico.com/x/JwKQC); for pages that do not have a published version, the version is migrated to the _Draft (Initial)_ status.
@@ -67,6 +67,7 @@ Currently, the Kentico Migration Tool supports the following types of data:
6767
- Custom settings under modules, which are currently not supported in Xperience by Kentico
6868
- Module permissions (permissions work differently in Xperience by Kentico - see [Role management](https://docs.kentico.com/x/7IVwCg) and [UI page permission checks](https://docs.kentico.com/x/8IKyCg))
6969
- As with all object types, the Kentico Migration Tool does not transfer code files to the target project. You must manually move all code files generated for your custom classes (_Info_, _InfoProvider_, etc.).
70+
- Module classes and the stored data can optionally be migrated as [reusable content items](https://docs.kentico.com/x/content_items_xp) in Content hub.
7071
- **Custom tables**
7172
- Custom tables are not supported in Xperience by Kentico. Data from custom tables can be migrated to the target instance either as [custom module classes](https://docs.kentico.com/x/AKDWCQ) (default behavior) or as [reusable content items](https://docs.kentico.com/x/content_items_xp) in Content hub.
7273
- Any user interface, listings, filters, and other functionality related to migrated custom tables needs to be implemented in the target instance.

0 commit comments

Comments
 (0)