diff --git a/Migration.Tool.CLI/README.md b/Migration.Tool.CLI/README.md index edab412f..f35dd1f5 100644 --- a/Migration.Tool.CLI/README.md +++ b/Migration.Tool.CLI/README.md @@ -59,11 +59,11 @@ Migration.Tool.CLI.exe migrate --sites --custom-modules --users --members --form | `--page-types` | Enables migration of [content types](https://docs.xperience.io/x/gYHWCQ) (originally *page types* in Kentico Xperience 13) and [preset page templates](https://docs.xperience.io/x/KZnWCQ) (originally *custom page templates*). Required to migrate Pages.

See: [Migration details for specific object types - Content types](#content-types) | `--sites` | | `--pages` | Enables migration of [pages](https://docs.xperience.io/x/bxzfBw).

The target instance must not contain pages other than those created by previous runs of the Kentico Migration Tool.

See: [Migration details for specific object types - Pages](#pages) | `--sites`, `--users`, `--page-types` | | `--categories` | Enables migration of categories to taxonomies. Xperience by Kentico uses a different approach to categorization. Categories are migrated to [taxonomies](https://docs.kentico.com/x/taxonomies_xp) and selected categories for each page are assigned to pages in the target instance via a [reusable field schema](https://docs.kentico.com/x/D4_OD). See [`Categories`](#categories). | `--sites`, `--users`, `--pagetypes`, `--pages` | -| `--attachments` | Enables migration of page attachments to [media libraries](https://docs.xperience.io/x/agKiCQ) (page attachments are not supported in Xperience by Kentico).

See: [Migration details for specific object types - Attachments](#attachments) | `--sites`, `--custom-modules` | +| `--attachments` | Enables migration of page attachments to [content hub](https://docs.kentico.com/x/barWCQ) as content item assets (page attachments are not supported in Xperience by Kentico).

See: [Migration details for specific object types - Attachments](#attachments) | `--sites`, `--custom-modules` | | `--contact-management` | Enables migration of [contacts](https://docs.xperience.io/x/nYPWCQ) and [activities](https://docs.xperience.io/x/oYPWCQ). The target instance must not contain any contacts or activities. May run for a long time depending on the number of contacts in the source database. | `--users`, `--custom-modules` | | `--data-protection` | Enables migration of [consents](https://docs.xperience.io/x/zoB1CQ) and consent agreements. | `--sites`, `--users`, `--contact management` | | `--forms` | Enables migration of [forms](https://docs.xperience.io/x/WAKiCQ) and submitted form data.

See: [Migration details for specific object types - Forms](#forms) | `--sites`, `--custom-modules`, `--users` | -| `--media-libraries` | Enables migration of [media libraries](https://docs.xperience.io/x/agKiCQ) and contained media files. The actual binary files are only migrated between file systems if the `MigrateOnlyMediaFileInfo` [configuration option](#configuration) is set to *false*. | `--sites`, `--custom-modules`, `--users` | +| `--media-libraries` | Enables migration of [media libraries](https://docs.xperience.io/x/agKiCQ) to [content hub](https://docs.kentico.com/x/barWCQ) as content item assets. This behavior can be adjusted by `MigrateOnlyMediaFileInfo` and `MigrateMediaToMediaLibrary` [configuration options](#configuration). | `--sites`, `--custom-modules`, `--users` | | `--countries` | Enables migration of countries and states. Xperience by Kentico currently uses countries and states to fill selectors when editing contacts and contact group conditions. | | | `--bypass-dependency-check` | Skips the migrate command's dependency check. Use for repeated runs of the migration if you know that dependencies were already migrated successfully (for example `--page types` when migrating pages). | | @@ -124,9 +124,9 @@ type fields: | Unique identifier (Guid) | Unique identifier (Guid) | *any* | None (not supported) | | Pages | Pages | *any* (Pages) | Page selector | -Additionally, you can enable the Conversion of text fields with media links (*Media selection* form control) to media +Additionally, you can enable the Conversion of text fields with media links (*Media selection* form control) to content item assets or media library files by setting -the `OptInFeatures.CustomMigration.FieldMigrations` [configuration option](#convert-text-fields-with-media-links-to-media-libraries). +the `OptInFeatures.CustomMigration.FieldMigrations` [configuration option](#convert-text-fields-with-media-links). Some [Form components](https://docs.xperience.io/x/5ASiCQ) used by content type fields in Xperience by Kentico store data differently than their equivalent Form control in Xperience 13. To ensure that content is displayed correctly on @@ -268,46 +268,15 @@ Custom table migration does NOT include: #### Media libraries -* In Xperience by Kentico, Media libraries are global instead of site-specific. -* The code name of each media library on the target instance is `{SiteName}_{LibraryCodeName}`. -* Media library permissions are currently not supported in Xperience by Kentic and are not migrated. - -#### Attachments +Media library files are migrated as content item assets to the [content hub](https://docs.kentico.com/x/barWCQ) into a content folder `/`. All assets are created in the default language of the respective site. Migrated assets are created as content items of a *Legacy media file* content type (code name `Legacy.Mediafile`) created by the tool. -Page attachments are not supported in Xperience by Kentico. Attachment files are instead migrated -into [media libraries](https://docs.xperience.io/x/agKiCQ). +If required, you can [configure the tool](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) to instead migrate media libraries as media libraries on the target instance. -* Page attachments are migrated into a media library named: *"Attachments for site \"* -* The media library contains folders matching the content tree structure for all pages with attachments (including empty - folders for parent pages without attachments). The folders are named after the *node alias* of the source pages. - * Each page's folder directly contains all unsorted attachments (files added on the *Attachments* tab in the - source's *Pages* application). - * Attachments stored in specific page fields are placed into subfolders, named in format: *"__fieldname"*. These - subfolders can include multiple files for fields of the *Attachments* type, or a single file for *File* type - fields. -* Any "floating" attachments without an associated page are migrated into the media library root folder. -* The migration does not include temporary attachments (created when a file upload is not finished correctly). If any - are present on the source instance, a warning is logged in - the [migration protocol](./MIGRATION_PROTOCOL_REFERENCE.md). - -The following is an example of a media library created by the Kentico Migration Tool for page attachments: - -#### Media library "Attachments for site DancingGoat" - -* **Articles** (empty parent folder) - * **Coffee-processing-techniques** (contains any unsorted attachments of the ' - /Articles/Coffee-processing-techniques' page) - * **__Teaser** (contains attachments stored in the page's 'Teaser' field) - * **Which-brewing-fits-you** - * **__Teaser** - * ... +#### Attachments -Additionally, any attachments placed into the content of migrated pages **will no longer work** in Xperience by Kentico. -This includes images and file download links that use **/getattachment** and **/getimage** URLs. +Attachment files are migrated as content item assets to the [content hub](https://docs.kentico.com/x/barWCQ) into a content folder `/__Attachments`. Assets are created in the specified language if the language is available (e.g., attachments of pages). Migrated assets are created as content items of a *Legacy attachment* content type (code name `Legacy.Attachment`) created by the tool. -If you wish to continue using these legacy attachment URLs from earlier Kentico versions, you need to add a custom -handler to your Xperience by Kentico project. -See [`Migration.Tool.KXP.Extensions/README.MD`](/Migration.Tool.KXP.Extensions/README.MD) for instructions. +If required, you can [configure the tool](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) to instead migrate attachments as media libraries on the target instance. #### Forms @@ -420,6 +389,7 @@ Add the options under the `Settings` section in the configuration file. | XbKApiSettings | Configuration options set for the API when creating migrated objects in the target application.

The `ConnectionStrings.CMSConnectionString`option is required - set the connection string to the target Xperience by Kentico database (the same value as `XbKConnectionString`). | | MigrationProtocolPath | The absolute file system path of the location where the [migration protocol file](./MIGRATION_PROTOCOL_REFERENCE.md) is generated.

For example: `"C:\\Logs\\Migration.Tool.Protocol.log"` | | 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.

If `false`, media files are migrated based on the `KxCmsDirPath` location. | +| 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/barWCQ) in the content hub. The default value is `false` – media files and attachments are migrated as content item assets.

See [Convert attachments and media library files to media libraries instad of content item assets](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) | | MemberIncludeUserSystemFields | Determines which system fields from the *CMS_User* and *CMS_UserSettings* tables are migrated to *CMS_Member* in Xperience by Kentico. Fields that do not exist in *CMS_Member* are automatically created.

The sample `appsettings.json` file included with the tool by default includes all user fields that can be migrated from Kentico Xperience 13. Exclude specific fields from the migration by removing them from this configuration option. | | UseOmActivityNodeRelationAutofix | Determines how the migration handles references from Contact management activities to non-existing pages.

Possible options:
`DiscardData` - faulty references are removed,
`AttemptFix` - references are updated to the IDs of corresponding pages created by the migration,
`Error` - an error is reported and the reference can be translated or otherwise handled manually | | UseOmActivitySiteRelationAutofix | Determines how the migration handles site references from Contact management activities.

Possible options: `DiscardData`,`AttemptFix`,`Error` | @@ -427,8 +397,8 @@ Add the options under the `Settings` section in the configuration file. | EntityConfigurations.*<object table name>*.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). | | 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:
`SourceInstanceUri` - the base URI where the source instance's live site application is running.
`Secret` - the secret that you set in the *ToolApiController.cs* file on the source instance. | -| OptInFeatures.CustomMigration.FieldMigrations | Enables conversion of media selection text fields to media library files. See [Convert text fields with media links to media libraries](#convert-text-fields-with-media-links-to-media-libraries) for more information. | +| 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:
`SourceInstanceUri` - the base URI where the source instance's live site application is running.
`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. | ### Example @@ -456,50 +426,51 @@ Add the options under the `Settings` section in the configuration file. "CMSConnectionString": "Data Source=myserver;Initial Catalog=XperienceByKentico;Integrated Security=True;Persist Security Info=False;Connect Timeout=120;Encrypt=False;Current Language=English;" } }, - "MigrationProtocolPath": "C:\\_Development\\xperience-migration-tool-master\\Migration.Tool.Protocol.log", - "MemberIncludeUserSystemFields": "FirstName|MiddleName|LastName|FullName|UserPrivilegeLevel|UserIsExternal|LastLogon|UserLastModified|UserGender|UserDateOfBirth", - "MigrateOnlyMediaFileInfo": false, - "UseOmActivityNodeRelationAutofix": "AttemptFix", - "UseOmActivitySiteRelationAutofix": "AttemptFix", - "EntityConfigurations": { - "CMS_Site": { - "ExplicitPrimaryKeyMapping": { - "SiteID": { - "1": 1 - } + "MigrationProtocolPath": "C:\\_Development\\xperience-migration-toolkit-master\\Migration.Toolkit.Protocol.log", + "MemberIncludeUserSystemFields": "FirstName|MiddleName|LastName|FullName|UserPrivilegeLevel|UserIsExternal|LastLogon|UserLastModified|UserGender|UserDateOfBirth", + "MigrateOnlyMediaFileInfo": false, + "MigrateMediaToMediaLibrary": false, + "UseOmActivityNodeRelationAutofix": "AttemptFix", + "UseOmActivitySiteRelationAutofix": "AttemptFix", + "EntityConfigurations": { + "CMS_Site": { + "ExplicitPrimaryKeyMapping": { + "SiteID": { + "1": 1 } - }, - "CMS_Class": { - "ExcludeCodeNames": [ - "CMS.File", - "CMS.MenuItem", - "ACME.News", - "ACME.Office", - "CMS.Blog", - "CMS.BlogPost" + } + }, + "CMS_Class": { + "ExcludeCodeNames": [ + "CMS.File", + "CMS.MenuItem", + "ACME.News", + "ACME.Office", + "CMS.Blog", + "CMS.BlogPost" + ] + }, + "CMS_SettingsKey": { + "ExcludeCodeNames": [ + "CMSHomePagePath" + ] + } + }, + "OptInFeatures":{ + "QuerySourceInstanceApi": { + "Enabled": true, + "Connections": [ + { "SourceInstanceUri": "http://localhost:60527", "Secret": "__your secret string__" } ] }, - "CMS_SettingsKey": { - "ExcludeCodeNames": [ - "CMSHomePagePath" - ] + "FieldMigrations": { + "SourceDataType": "text", + "TargetDataType": "assets", + "SourceFormControl": "MediaSelectionControl", + "TargetFormComponent": "Kentico.Administration.AssetSelector", + "Actions": [ "convert to asset" ], + "FieldNameRegex": ".*" } - }, - "OptInFeatures":{ - "QuerySourceInstanceApi": { - "Enabled": true, - "Connections": [ - { "SourceInstanceUri": "http://localhost:60527", "Secret": "__your secret string__" } - ] - }, - "FieldMigrations": { - "SourceDataType": "text", - "TargetDataType": "assets", - "SourceFormControl": "MediaSelectionControl", - "TargetFormComponent": "Kentico.Administration.AssetSelector", - "Actions": [ "convert to asset" ], - "FieldNameRegex": ".*" - } } } } @@ -652,17 +623,12 @@ The following example specifies two page types from which reusable schemas are c same code name, the code name is prefixed with the content type name in the converted reusable field schemas. > * Page types specified by this configuration option are also migrated as content types into to the target instance. -## Convert text fields with media links to media libraries +## Convert text fields with media links By default, page type and module class fields with the _Text_ data type and the _Media selection_ [form control](https://docs.xperience.io/x/0A_RBg) from the source instance are converted to plain _Text_ fields in the target instance. You can instead configure the Kentico Migration Tool to convert these fields to the -_Media files_ data type and use the _Media file selector_ form component. - -* Attachment links (containing a `getattachment` handler) are migrated as [attachments](#attachments) and changed to the - _Media files_ data type. -* Media file links (containing a `getmedia` handler) are changed to the _Media files_ data type. It is expected that the - media library containing the targeted file has been migrated. +_Content items_ data type and use the _Content item selector_ form component, or _Media files_ data type and use the _Media file selector_ form component if you choose to [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). > :warning: **Notes** > @@ -677,6 +643,40 @@ _Media files_ data type and use the _Media file selector_ form component. > * If the target instance is a [SaaS project](https://docs.kentico.com/x/saas_xp), you need to manually move content item asset files. See [Content items](#content-items) for more information. +### Convert to content item assets + +To enable this feature, configure the `OptInFeatures.CustomMigration.FieldMigrations` [options](#configuration) for this +tool. Use the values in the code snippet below: + +```json +"OptInFeatures": { + "CustomMigration": { + "FieldMigrations": [ + { + "SourceDataType": "text", + "TargetDataType": "contentitemreference", + "SourceFormControl": "MediaSelectionControl", + "TargetFormComponent": "Kentico.Administration.ContentItemSelector", + "Actions": [ + "convert to asset" + ], + "FieldNameRegex": ".*" + } + ] + } +} +``` + +`FieldNameRegex` - a regular expression used to filter what fields are converted. Only fields with field names that +match the regular expressions are converted. Use `.*` to match all fields. + +### Convert to media libraries + +* Attachment links (containing a `getattachment` handler) are migrated as [attachments](#attachments) and changed to the + _Media files_ data type. +* Media file links (containing a `getmedia` handler) are changed to the _Media files_ data type. It is expected that the + media library containing the targeted file has been migrated. + To enable this feature, configure the `OptInFeatures.CustomMigration.FieldMigrations` [options](#configuration) for this tool. Use the values in the code snippet below: @@ -699,3 +699,38 @@ tool. Use the values in the code snippet below: `FieldNameRegex` - a regular expression used to filter what fields are converted. Only fields with field names that match the regular expressions are converted. Use `.*` to match all fields. + +## Convert attachments and media library files to media libraries instead of content item assets + +By default, media libraries and attachments are migrated as content item assets in the target instance, which is the recommended approach to ensure future-proofing of project and improve the [content model](https://docs.kentico.com/x/f4HWCQ). You can modify this behavior by configuring the value of the `MigrateMediaToMediaLibrary` setting to `true` and convert media library files and attachments to media libraries if you want to continue using media libraries. When set to `false`, media libraries and attachments are migrated as content item assets in the target instance. + +### Media libraries + +* In Xperience by Kentico, Media libraries are global instead of site-specific. +* The code name of each media library on the target instance is `{SiteName}_{LibraryCodeName}`. +* Media library permissions are currently not supported in Xperience by Kentico and are not migrated. + +### Attachments + +* Page attachments are migrated into a media library named: *"Attachments for site \"* +* The media library contains folders matching the content tree structure for all pages with attachments (including empty folders for parent pages without attachments). The folders are named after the *node alias* of the source pages. +* Each page's folder directly contains all unsorted attachments (files added on the *Attachments* tab in the source's *Pages* application). +* Attachments stored in specific page fields are placed into subfolders, named in format: *"__fieldname"*. These subfolders can include multiple files for fields of the *Attachments* type, or a single file for *File* type fields. +* Any "floating" attachments without an associated page are migrated into the media library root folder. +* The migration does not include temporary attachments (created when a file upload is not finished correctly). If any are present on the source instance, a warning is logged in the [migration protocol](./MIGRATION_PROTOCOL_REFERENCE.md). + +The following is an example of a media library created by the Kentico Migration Tool for page attachments: + +* **Articles** (empty parent folder) + * **Coffee-processing-techniques** (contains any unsorted attachments of the '/Articles/Coffee-processing-techniques' page) + * **__Teaser** (contains attachments stored in the page's 'Teaser' field) + * **Which-brewing-fits-you** + * **__Teaser** + * ... + +Additionally, any attachments placed into the content of migrated pages **will no longer work** in Xperience by Kentico. +This includes images and file download links that use **/getattachment** and **/getimage** URLs. + +If you wish to continue using these legacy attachment URLs from earlier Kentico versions, you need to add a custom +handler to your Xperience by Kentico project. +See [`Migration.Toolkit.KXP.Extensions/README.MD`](/Migration.Toolkit.KXP.Extensions/README.MD) for instructions. diff --git a/Migration.Tool.KXP.Extensions/README.MD b/Migration.Tool.KXP.Extensions/README.MD index 72336718..b21b8e62 100644 --- a/Migration.Tool.KXP.Extensions/README.MD +++ b/Migration.Tool.KXP.Extensions/README.MD @@ -10,9 +10,7 @@ to [add a custom handler](#add-the-handler-to-your-project) to your Xperience by ### Prerequisite -To ensure that the handler provided in the `LegacyAttachmentHandler.cs` file works correctly, you need -to [migrate](/Migration.Tool.CLI/README.md) your page attachments into a media library, and **keep the default folder -structure and file names**. +To ensure that the handler provided in the `LegacyAttachmentHandler.cs` file works correctly, you need to [migrate](/Migration.Toolkit.CLI/README.md) your page attachments into a **media library** using the `MigrateMediaToMediaLibrary` configuration option, and **keep the default folder structure and file names**. By default, attachments are migrated into the content hub and the handler is not applicable. ### Attachment URLs in content diff --git a/README.md b/README.md index 1dcba123..5dba5dae 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ The Kentico Migration Tool transfers content and other data from **Kentico Xperi | == 29.1.0 | == 1.0.0 | | == 29.2.0 | == 1.1.0 | | == 29.3.3 | == 1.2.0 | +| == 29.5.2 | == 1.3.0 | ## Dependencies @@ -55,6 +56,9 @@ View the [Usage Guide](./docs/Usage-Guide.md) for more detailed instructions. ## Changelog of recent updates +- **September 4, 2024** + - Migration of media libraries and attachments to assets is available + - Media libraries and attachments are now [migrated](/Migration.Toolkit.CLI/README.md#media-libraries) to content item assets by default - **June 13, 2024** - Migration of categories to taxonomies is available - **March 11, 2024**