From e5143628df65b229e555da29421a7909f0978d4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C5=A0lezar?= Date: Tue, 22 Oct 2024 13:46:59 +0200 Subject: [PATCH 1/8] Added the proposed changes --- Migration.Toolkit.CLI/README.md | 8 +++++--- README.md | 19 ++++++++++++++----- global.json | 12 ++++++------ 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/Migration.Toolkit.CLI/README.md b/Migration.Toolkit.CLI/README.md index 6d99435a..8a1036d5 100644 --- a/Migration.Toolkit.CLI/README.md +++ b/Migration.Toolkit.CLI/README.md @@ -323,7 +323,9 @@ The migration includes: * All system fields from the *CMS_User* and *CMS_UserSettings* tables. You can customize which fields are migrated via the `MemberIncludeUserSystemFields` configuration option. See [configuration](#configuration). -* All custom fields added to the *CMS_User* and *CMS_UserSettings* tables are migrated under `CMS_Member`. +* All custom fields added to the *CMS_User* and *CMS_UserSettings* tables are migrated under `CMS_Member`. The columns specified in the `MemberIncludeSystemFields` option are appended to the `CMS_Member` table in the order in which they were specified. For example for `MemberIncludeSystemFields: "MemberIncludeUserSystemFields": "FirstName|LastName|UserPrivilegeLevel` the structure looks like this after migration: +* MemberId|MemberEmail|...|MemberSecurityStamp| -> |MemberId|MemberEmail|...|MemberSecurityStamp|FirstName|LastName|UserPrivilegeLevel| + * where *...* represent the remaining columns from the `CMS_Member` table. > If you are migrating custom fields, the `--custom-modules` migration command must be run before the `--members` command. For example: @@ -383,8 +385,8 @@ Add the options under the `Settings` section in the configuration file. | Configuration | Description | |-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| KxConnectionString | The connection string to the source Kentico Xperience 13 database. | -| KxCmsDirPath | The absolute file system path of the **CMS** folder in the source Kentico Xperience 13 administration project. Required to migrate media library files. | +| KxConnectionString | The connection string to the source Kentico Xperience 13, Kentico 12, or Kentico 11 database. | +| KxCmsDirPath | The absolute file system path of the **CMS** folder in the source Kentico Xperience 13, Kentico 12, or Kentico 11 administration project. Required to migrate media library files. | | XbKDirPath | The absolute file system path of the root of the target Xperience by Kentico project. Required to migrate media library and page attachment files. | | 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"` | diff --git a/README.md b/README.md index 26c62136..33ca70d1 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,13 @@ This repository is part of the [Xperience by Kentico Migration Toolkit](https:// The Kentico Migration Tool transfers content and other data from **Kentico Xperience 13**, **Kentico 12** or **Kentico 11** to **Xperience by Kentico**. +This repository contains several README documents containing information necessary for the correct usage of the Kentico Migration Tool. Namely: + +- [Migration CLI](./Migration.Toolkit.CLI/README.md) -- information about the necessary set up before running the Kentico Migration Tool. +- [Usage Guide](./docs/Usage-Guide.md) -- information about what kind of projects the Kentico Migration Tool supports. +- [Supported Data](./docs/Supported-Data.md) -- lists all available data for migration +- [Migration Protocol](./Migration.Toolkit.CLI/MIGRATION_PROTOCOL_REFERENCE.md) -- provides information about the results of the migration and required manual steps, etc. + ## Library Version Matrix | Xperience Version | Library Version | @@ -31,17 +38,19 @@ Follow the steps below to run the Kentico Migration Tool: 1. Clone or download the Migration.Toolkit source code from this repository. 2. Open the `Migration.Toolkit.sln` solution in Visual Studio. 3. Configure the options in the `Migration.Toolkit.CLI/appsettings.json` configuration file. See [`Migration.Toolkit.CLI/README.md - Configuration`](./Migration.Toolkit.CLI/README.md#Configuration) for details. -4. Rebuild the solution and restore all required NuGet packages. +4. Rebuild the Kentico Migration Tool solution, which by default restores potentionally missing NuGet packages and incorporates applied configuration changes to the `Migration.Toolkit.CLI.exe` file. 5. Open the command line prompt. -6. Navigate to the output directory of the `Migration.Toolkit.CLI` project. +6. Navigate to the output directory of the `Migration.Toolkit.CLI` project. (under `.\Migration.Toolkit.CLI\bin\Debug\net8.0\`) 7. Run the `Migration.Toolkit.CLI.exe migrate` command. - The following example shows the command with all parameters for complete migration: ```powershell - Migration.Toolkit.CLI.exe migrate --sites --custom-modules --users --settings-keys --page-types --pages --attachments --contact-management --forms --media-libraries --data-protection --countries + .\Migration.Toolkit.CLI.exe migrate --sites --custom-modules --users --settings-keys --page-types --pages --attachments --contact-management --forms --media-libraries --data-protection --countries --custom-tables --members --categories ``` + - You can migrate your projects iteratively. For repeated runs bypass depency checks by using the `--bypass-dependency-check` parameter, if you know that required dependencies were already migrated succesfully. + 8. Observe the command line output. The command output is also stored in a log file (`logs\log-.txt` under the output directory by default), which you can review later. 9. Review the migration protocol, which provides information about the result of the migration, lists required manual steps, etc. @@ -50,9 +59,9 @@ Follow the steps below to run the Kentico Migration Tool: The data is now migrated to the target Xperience by Kentico instance according to your configuration. See [`Migration.Toolkit.CLI/README.md`](./Migration.Toolkit.CLI/README.md) for detailed information about the migration CLI, configuration options, instructions related to individual object types, and manual migration steps. -## Full Instructions +## Full Requirements -View the [Usage Guide](./docs/Usage-Guide.md) for more detailed instructions. +View the [Usage Guide](./docs/Usage-Guide.md) for information about what kind of projects the Kentico Migration Tool supports. ## Changelog of recent updates diff --git a/global.json b/global.json index 0a0c1515..72d38cd2 100644 --- a/global.json +++ b/global.json @@ -1,7 +1,7 @@ -{ - "sdk": { - "version": "8.0.100", - "rollForward": "latestMajor", - "allowPrerelease": false - } +{ + "sdk": { + "version": "8.0.100", + "rollForward": "latestMajor", + "allowPrerelease": false + } } \ No newline at end of file From b01252ce23cd1ec3634a7e02a01aae44df216e4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C5=A0lezar?= Date: Tue, 22 Oct 2024 13:48:04 +0200 Subject: [PATCH 2/8] another one of those.. --- global.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/global.json b/global.json index 0a0c1515..72d38cd2 100644 --- a/global.json +++ b/global.json @@ -1,7 +1,7 @@ -{ - "sdk": { - "version": "8.0.100", - "rollForward": "latestMajor", - "allowPrerelease": false - } +{ + "sdk": { + "version": "8.0.100", + "rollForward": "latestMajor", + "allowPrerelease": false + } } \ No newline at end of file From 965bb6698ffaad6fcdf7ff6f8a819df1012bc951 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C5=A0lezar?= Date: Tue, 22 Oct 2024 13:54:40 +0200 Subject: [PATCH 3/8] merge master to documentation branch --- Migration.Toolkit.Common/Resources.Designer.cs | 1 + 1 file changed, 1 insertion(+) diff --git a/Migration.Toolkit.Common/Resources.Designer.cs b/Migration.Toolkit.Common/Resources.Designer.cs index ebe1faf1..27710510 100644 --- a/Migration.Toolkit.Common/Resources.Designer.cs +++ b/Migration.Toolkit.Common/Resources.Designer.cs @@ -1,6 +1,7 @@ //------------------------------------------------------------------------------ // // This code was generated by a tool. +// Runtime Version:4.0.30319.42000 // // Changes to this file may cause incorrect behavior and will be lost if // the code is regenerated. From 5d515843311b3179555e9063645f6770aae7c8b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C5=A0lezar?= Date: Wed, 23 Oct 2024 08:23:13 +0200 Subject: [PATCH 4/8] refixed after solving conflicts --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cb7b1361..269603ee 100644 --- a/README.md +++ b/README.md @@ -41,13 +41,13 @@ Follow the steps below to run the Kentico Migration Tool: 3. Configure the options in the `Migration.Tool.CLI/appsettings.json` configuration file. See [`Migration.Tool.CLI/README.md - Configuration`](./Migration.Tool.CLI/README.md#Configuration) for details. 4. Rebuild the solution and restore all required NuGet packages. 5. Open the command line prompt. -6. Navigate to the output directory of the `Migration.Tool.CLI` project. +6. Navigate to the output directory of the `Migration.Tool.CLI` project. (under `.\Migration.Toolkit.CLI\bin\Debug\net8.0\`) 7. Run the `Migration.Tool.CLI.exe migrate` command. - The following example shows the command with all parameters for complete migration: ```powershell - Migration.Tool.CLI.exe migrate --sites --custom-modules --users --settings-keys --page-types --pages --attachments --contact-management --forms --media-libraries --data-protection --countries + .\Migration.Tool.CLI.exe migrate --sites --custom-modules --users --settings-keys --page-types --pages --attachments --contact-management --forms --media-libraries --data-protection --countries --custom-tables --members --categories ``` - You can migrate your projects iteratively. For repeated runs bypass depency checks by using the `--bypass-dependency-check` parameter, if you know that required dependencies were already migrated succesfully. From e8ea81b97e7e20d8688c45ff49578bf4f1c72dc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C5=A0lezar?= Date: Wed, 23 Oct 2024 08:24:42 +0200 Subject: [PATCH 5/8] updated the version --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 269603ee..9543a008 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ This repository contains several README documents containing information necessa | == 29.2.0 | == 1.1.0 | | == 29.3.3 | == 1.2.0 | | == 29.5.2 | == 1.3.0 | -| == 29.5.2 | == 1.4.0 | +| == 29.6.0 | == 1.4.0 | ## Dependencies From 0f7ee11df3de0d6c0d6ace940011884163e2fa2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C5=A0lezar?= Date: Wed, 23 Oct 2024 08:34:19 +0200 Subject: [PATCH 6/8] changed the formatiing --- Migration.Tool.CLI/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Migration.Tool.CLI/README.md b/Migration.Tool.CLI/README.md index 3a357c77..acbba1c2 100644 --- a/Migration.Tool.CLI/README.md +++ b/Migration.Tool.CLI/README.md @@ -324,8 +324,7 @@ The migration includes: * All system fields from the *CMS_User* and *CMS_UserSettings* tables. You can customize which fields are migrated via the `MemberIncludeUserSystemFields` configuration option. See [configuration](#configuration). * All custom fields added to the *CMS_User* and *CMS_UserSettings* tables are migrated under `CMS_Member`. The columns specified in the `MemberIncludeSystemFields` option are appended to the `CMS_Member` table in the order in which they were specified. For example for `MemberIncludeSystemFields: "MemberIncludeUserSystemFields": "FirstName|LastName|UserPrivilegeLevel` the structure looks like this after migration: -* MemberId|MemberEmail|...|MemberSecurityStamp| -> |MemberId|MemberEmail|...|MemberSecurityStamp|FirstName|LastName|UserPrivilegeLevel| - * where *...* represent the remaining columns from the `CMS_Member` table. + * `|MemberId|MemberEmail|...|MemberSecurityStamp|` -> `|MemberId|MemberEmail|...|MemberSecurityStamp|FirstName|LastName|UserPrivilegeLevel|` > If you are migrating custom fields, the `--custom-modules` migration command must be run before the `--members` command. For example: From 202fb1282cda750aa01a63d1fdf21e3a910d373a Mon Sep 17 00:00:00 2001 From: "Sean G. Wright" Date: Wed, 6 Nov 2024 11:37:40 -0500 Subject: [PATCH 7/8] docs(CLI): Member fields migration --- Migration.Tool.CLI/README.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/Migration.Tool.CLI/README.md b/Migration.Tool.CLI/README.md index acbba1c2..3862e5b6 100644 --- a/Migration.Tool.CLI/README.md +++ b/Migration.Tool.CLI/README.md @@ -323,8 +323,27 @@ The migration includes: * All system fields from the *CMS_User* and *CMS_UserSettings* tables. You can customize which fields are migrated via the `MemberIncludeUserSystemFields` configuration option. See [configuration](#configuration). -* All custom fields added to the *CMS_User* and *CMS_UserSettings* tables are migrated under `CMS_Member`. The columns specified in the `MemberIncludeSystemFields` option are appended to the `CMS_Member` table in the order in which they were specified. For example for `MemberIncludeSystemFields: "MemberIncludeUserSystemFields": "FirstName|LastName|UserPrivilegeLevel` the structure looks like this after migration: - * `|MemberId|MemberEmail|...|MemberSecurityStamp|` -> `|MemberId|MemberEmail|...|MemberSecurityStamp|FirstName|LastName|UserPrivilegeLevel|` +* All custom fields added to the *CMS_User* and *CMS_UserSettings* tables are migrated under `CMS_Member`. The columns specified in the `MemberIncludeSystemFields` option are appended to the `CMS_Member` table in the order in which they were specified. + As an example, take the following `CMS_Member` columns + + ```text + |MemberId|MemberEmail|...|MemberSecurityStamp| + ``` + + And the following `Migration.Tool.CLI/appsettings.json` configuration. + + ```json + { + "MemberIncludeUserSystemFields": "FirstName|LastName|UserPrivilegeLevel" + } + ``` + + This will result in the following `CMS_Member` structure after migration. + + ```text + |MemberId|MemberEmail|...|MemberSecurityStamp|FirstName|LastName|UserPrivilegeLevel|` + ``` + > If you are migrating custom fields, the `--custom-modules` migration command must be run before the `--members` command. For example: From f93c4e61e380ec5dbf410abc15a2c65718426933 Mon Sep 17 00:00:00 2001 From: "Sean G. Wright" Date: Wed, 6 Nov 2024 11:37:57 -0500 Subject: [PATCH 8/8] docs(README): library version matrix version order --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9543a008..c37ffdce 100644 --- a/README.md +++ b/README.md @@ -21,11 +21,11 @@ This repository contains several README documents containing information necessa | Xperience Version | Library Version | | ----------------- | --------------- | -| == 29.1.0 | == 1.0.0 | -| == 29.2.0 | == 1.1.0 | -| == 29.3.3 | == 1.2.0 | -| == 29.5.2 | == 1.3.0 | -| == 29.6.0 | == 1.4.0 | +| 29.6.0 | 1.4.0 | +| 29.5.2 | 1.3.0 | +| 29.3.3 | 1.2.0 | +| 29.2.0 | 1.1.0 | +| 29.1.0 | 1.0.0 | ## Dependencies