From 3641853c2e6297510e5552b206c957d6e0510dfb Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 3 Oct 2024 15:47:55 +0200 Subject: [PATCH 1/9] ML to asset migration --- Migration.Toolkit.CLI/README.md | 108 ++++++++++++++++++++------------ README.md | 4 +- 2 files changed, 71 insertions(+), 41 deletions(-) diff --git a/Migration.Toolkit.CLI/README.md b/Migration.Toolkit.CLI/README.md index fc230150..7bc6680e 100644 --- a/Migration.Toolkit.CLI/README.md +++ b/Migration.Toolkit.CLI/README.md @@ -420,6 +420,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.Toolkit.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 files (media library files and optionally attachments) from the source instance are migrated to the target instance as media libraries or as assets in the content hub.

See [Convert attachments and media library files to assets](#convert-attachments-and-media-library-files-to-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` | @@ -456,50 +457,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-toolkit-master\\Migration.Toolkit.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": ".*" - } } } } @@ -699,3 +701,29 @@ 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 assets + +By default, media libraries and attachments (if the `--attachments` parameter is enabled) are migrated to media libraries in the target instance. You can modify this behavior by configuring the value of the `MigrateMediaToMediaLibrary` setting to `false` and convert media library files and attachments to assets in the content hub. When set to `true`, media libraries and attachments are migrated into media libraries in the target instance. + +- Media library files are migrated to content hub into a content folder `/`. All assets are created in the default language of the respective site. +- Attachment files are migrated to content hub into a content folder `/__Attachments`. Assets are created in the specified language if the language is available (e.g., attachments of pages). + +```json +"OptInFeatures":{ + "CustomMigration":{ + "FieldMigrations": [ + { + "SourceDataType": "text", + "TargetDataType": "contentitemreference", + "SourceFormControl": "MediaSelectionControl", + "TargetFormComponent": "Kentico.Administration.ContentItemSelector", + "Actions": [ + "convert to asset" + ], + "FieldNameRegex": ".*" + } + ] + } +} +``` \ No newline at end of file diff --git a/README.md b/README.md index cdda0b73..206074c5 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ The Kentico Migration Tool transfers content and other data from **Kentico Xperi ## Library Version Matrix | Xperience Version | Library Version | -|-------------------|-----------------| +| ----------------- | --------------- | | == 29.1.0 | == 1.0.0 | | == 29.2.0 | == 1.1.0 | | == 29.3.3 | == 1.2.0 | @@ -55,6 +55,8 @@ 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 - **June 13, 2024** - Migration of categories to taxonomies is available - **March 11, 2024** From eebe38db604e78aea0920b9fccfa5d16eb767851 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Fri, 4 Oct 2024 16:16:10 +0200 Subject: [PATCH 2/9] change default behav --- Migration.Toolkit.CLI/README.md | 89 ++++++++++++--------------------- 1 file changed, 31 insertions(+), 58 deletions(-) diff --git a/Migration.Toolkit.CLI/README.md b/Migration.Toolkit.CLI/README.md index 7bc6680e..0278484d 100644 --- a/Migration.Toolkit.CLI/README.md +++ b/Migration.Toolkit.CLI/README.md @@ -268,47 +268,14 @@ 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. +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. #### Attachments -Page attachments are not supported in Xperience by Kentico. Attachment files are instead migrated -into [media libraries](https://docs.xperience.io/x/agKiCQ). - -* 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). +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. 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** - * ... - -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. - #### Forms The migration does not include the content of form autoresponder and notification emails. @@ -420,7 +387,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.Toolkit.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 files (media library files and optionally attachments) from the source instance are migrated to the target instance as media libraries or as assets in the content hub.

See [Convert attachments and media library files to assets](#convert-attachments-and-media-library-files-to-assets) | +| 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` | @@ -702,28 +669,34 @@ 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 assets +## Convert attachments and media library files to media libraries instead of content item assets -By default, media libraries and attachments (if the `--attachments` parameter is enabled) are migrated to media libraries in the target instance. You can modify this behavior by configuring the value of the `MigrateMediaToMediaLibrary` setting to `false` and convert media library files and attachments to assets in the content hub. When set to `true`, media libraries and attachments are migrated into media libraries in the target instance. +By default, media libraries and attachments are migrated as content item assets in the target instance. 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 library files are migrated to content hub into a content folder `/`. All assets are created in the default language of the respective site. -- Attachment files are migrated to content hub into a content folder `/__Attachments`. Assets are created in the specified language if the language is available (e.g., attachments of pages). +* 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). -```json -"OptInFeatures":{ - "CustomMigration":{ - "FieldMigrations": [ - { - "SourceDataType": "text", - "TargetDataType": "contentitemreference", - "SourceFormControl": "MediaSelectionControl", - "TargetFormComponent": "Kentico.Administration.ContentItemSelector", - "Actions": [ - "convert to asset" - ], - "FieldNameRegex": ".*" - } - ] - } -} -``` \ No newline at end of file +### 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** + * ... + +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. From 83b9c904b3491b3ce998a92a477b99d6e1976090 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Fri, 4 Oct 2024 16:39:19 +0200 Subject: [PATCH 3/9] ML to asset migration --- Migration.Toolkit.CLI/README.md | 56 ++++++++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 7 deletions(-) diff --git a/Migration.Toolkit.CLI/README.md b/Migration.Toolkit.CLI/README.md index 0278484d..3e5e2dd8 100644 --- a/Migration.Toolkit.CLI/README.md +++ b/Migration.Toolkit.CLI/README.md @@ -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 @@ -274,8 +274,6 @@ Media library files are migrated as content item assets to the [content hub](htt 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. -The following is an example of a media library created by the Kentico Migration Tool for page attachments: - #### Forms The migration does not include the content of form autoresponder and notification emails. @@ -396,7 +394,7 @@ Add the options under the `Settings` section in the configuration file. | 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 *ToolkitApiController.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.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 @@ -621,12 +619,54 @@ 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. +_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). + +### Convert to content item assets + +> :warning: **Notes** +> +> * Only media libraries using the **Permanent** [file URL format](https://docs.xperience.io/x/xQ_RBg) are supported. + Content from media libraries with enabled **Use direct path for files in content** setting will not be converted. +> * If you enable this feature, you also need to change retrieval and handling of affected files in your code, as the + structure of the stored data changes from a text path ( + e.g.,`~/getmedia/CCEAD0F0-E2BF-459B-814A-36699E5C773E/somefile.jpeg?width=300&height=100`) to a _Media files_ data + type (internally stored as + e.g., `[{"Identifier":"CCEAD0F0-E2BF-459B-814A-36699E5C773E","Some file":"somefile.jpeg","Size":11803,"Dimensions":{"Width":300,"Height":100}}]`). + The value of the field now needs to be [retrieved as a media library file](https://docs.xperience.io/x/LA2RBg). +> * 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. + +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. @@ -687,6 +727,8 @@ By default, media libraries and attachments are migrated as content item assets ### Media library "Attachments for site DancingGoat" +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) From 1faad7756b6e1bad047e3d0f625ef69860c181c1 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Fri, 4 Oct 2024 16:42:20 +0200 Subject: [PATCH 4/9] Migrate ML to assets --- Migration.Toolkit.CLI/README.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/Migration.Toolkit.CLI/README.md b/Migration.Toolkit.CLI/README.md index 3e5e2dd8..8a225294 100644 --- a/Migration.Toolkit.CLI/README.md +++ b/Migration.Toolkit.CLI/README.md @@ -626,8 +626,6 @@ selection_ [form control](https://docs.xperience.io/x/0A_RBg) from the source in fields in the target instance. You can instead configure the Kentico Migration Tool to convert these fields to the _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). -### Convert to content item assets - > :warning: **Notes** > > * Only media libraries using the **Permanent** [file URL format](https://docs.xperience.io/x/xQ_RBg) are supported. @@ -641,6 +639,8 @@ _Content items_ data type and use the _Content item selector_ form component, or > * 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: @@ -673,19 +673,6 @@ match the regular expressions are converted. Use `.*` to match all fields. * 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. -> :warning: **Notes** -> -> * Only media libraries using the **Permanent** [file URL format](https://docs.xperience.io/x/xQ_RBg) are supported. - Content from media libraries with enabled **Use direct path for files in content** setting will not be converted. -> * If you enable this feature, you also need to change retrieval and handling of affected files in your code, as the - structure of the stored data changes from a text path ( - e.g.,`~/getmedia/CCEAD0F0-E2BF-459B-814A-36699E5C773E/somefile.jpeg?width=300&height=100`) to a _Media files_ data - type (internally stored as - e.g., `[{"Identifier":"CCEAD0F0-E2BF-459B-814A-36699E5C773E","Some file":"somefile.jpeg","Size":11803,"Dimensions":{"Width":300,"Height":100}}]`). - The value of the field now needs to be [retrieved as a media library file](https://docs.xperience.io/x/LA2RBg). -> * 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. - To enable this feature, configure the `OptInFeatures.CustomMigration.FieldMigrations` [options](#configuration) for this tool. Use the values in the code snippet below: From 081e9e1141a4a4f10a2bbfe6eef78e81d9dfb3cc Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Fri, 4 Oct 2024 16:56:57 +0200 Subject: [PATCH 5/9] ML to assets --- Migration.Toolkit.CLI/README.md | 4 ++++ README.md | 1 + 2 files changed, 5 insertions(+) diff --git a/Migration.Toolkit.CLI/README.md b/Migration.Toolkit.CLI/README.md index 8a225294..6d99435a 100644 --- a/Migration.Toolkit.CLI/README.md +++ b/Migration.Toolkit.CLI/README.md @@ -270,10 +270,14 @@ Custom table migration does NOT include: 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. +You can [configure the tool](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) to migrate media libraries as media libraries to the target instance. + #### Attachments 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. +You can [configure the tool](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) to migrate attachments as media libraries to the target instance. + #### Forms The migration does not include the content of form autoresponder and notification emails. diff --git a/README.md b/README.md index 206074c5..4cb81acf 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ View the [Usage Guide](./docs/Usage-Guide.md) for more detailed instructions. - **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** From b3734d75187c5ab3d5ce08b48bf526cddc6a62f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Krch?= Date: Tue, 8 Oct 2024 11:05:40 +0200 Subject: [PATCH 6/9] version matrix update (#259) --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 4cb81acf..26c62136 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 From d09d2bffa29fe4a2a8a630f6ecebe584d97196c0 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 9 Oct 2024 17:44:39 +0200 Subject: [PATCH 7/9] Asset migration review --- Migration.Toolkit.CLI/README.md | 43 +++++++++++++++++---------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/Migration.Toolkit.CLI/README.md b/Migration.Toolkit.CLI/README.md index 6d99435a..94ead392 100644 --- a/Migration.Toolkit.CLI/README.md +++ b/Migration.Toolkit.CLI/README.md @@ -59,11 +59,11 @@ Migration.Toolkit.CLI.exe migrate --sites --custom-modules --users --members --f | `--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). | | @@ -270,13 +270,13 @@ Custom table migration does NOT include: 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. -You can [configure the tool](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) to migrate media libraries as media libraries to the target instance. +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. #### Attachments 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. -You can [configure the tool](#convert-attachments-and-media-library-files-to-media-libraries-instead-of-content-item-assets) to migrate attachments as media libraries to the target instance. +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 @@ -649,8 +649,8 @@ To enable this feature, configure the `OptInFeatures.CustomMigration.FieldMigrat tool. Use the values in the code snippet below: ```json -"OptInFeatures":{ - "CustomMigration":{ +"OptInFeatures": { + "CustomMigration": { "FieldMigrations": [ { "SourceDataType": "text", @@ -702,21 +702,22 @@ 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. 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). - -### Media library "Attachments for site DancingGoat" +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: From 2f78b28bcbac985fae811f672794b96b2d66911f Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 10 Oct 2024 14:49:51 +0200 Subject: [PATCH 8/9] legacy handler --- Migration.Toolkit.KXP.Extensions/README.MD | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Migration.Toolkit.KXP.Extensions/README.MD b/Migration.Toolkit.KXP.Extensions/README.MD index 72dc362b..706e3be9 100644 --- a/Migration.Toolkit.KXP.Extensions/README.MD +++ b/Migration.Toolkit.KXP.Extensions/README.MD @@ -1,5 +1,7 @@ ## Handler for legacy attachment URLs +> :warning: **Note**: This handler is only available when attachments are migrated as media libraries using the `MigrateMediaToMediaLibrary` configuration option. + Page attachments are not supported in Xperience by Kentico. Instead, the [Migration toolkit](/README.md) transfers attachment files into [media libraries](https://docs.xperience.io/x/agKiCQ). From 28768b3620fc9f69cbffcda3346b6c5978c92f2f Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 10 Oct 2024 14:52:09 +0200 Subject: [PATCH 9/9] handler --- Migration.Toolkit.KXP.Extensions/README.MD | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/Migration.Toolkit.KXP.Extensions/README.MD b/Migration.Toolkit.KXP.Extensions/README.MD index 706e3be9..16e29a8b 100644 --- a/Migration.Toolkit.KXP.Extensions/README.MD +++ b/Migration.Toolkit.KXP.Extensions/README.MD @@ -1,7 +1,5 @@ ## Handler for legacy attachment URLs -> :warning: **Note**: This handler is only available when attachments are migrated as media libraries using the `MigrateMediaToMediaLibrary` configuration option. - Page attachments are not supported in Xperience by Kentico. Instead, the [Migration toolkit](/README.md) transfers attachment files into [media libraries](https://docs.xperience.io/x/agKiCQ). @@ -12,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.Toolkit.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