kentico / xperience-by-kentico-universal-migration-tool

Underlying technology to enable content and data imports from any data source into Xperience by Kentico.

Xperience by Kentico: Universal Migration Tool

Description

This repository is part of the Xperience by Kentico Migration Toolkit.

The Xperience by Kentico: Universal Migration Tool (UMT) is an open-source set of software libraries, documentation, and samples distributed via NuGet packages to facilitate and automate data import from external data sources into Xperience by Kentico.

Library Version Matrix

Xperience Version	Library Version
>= 29.1.0	>= 1.1.0

Dependencies

• .NET 8+ SDK
• Xperience by Kentico

Package Installation

Add the package to your application using the .NET CLI

dotnet add package Kentico.Xperience.UMT

Quick Start

1. Open file with dependency injection container configuration. (Program.cs / Startup.cs / ...)
2. Import namespace Kentico.Xperience.UMT.
3. Register Umt to service collection IServiceCollection using AddUniversalMigrationToolkit().
4. Inject IImportService where you want use this tool.

Full Instructions

View the Docs for more detailed instructions.

Projects

Project	Description
src/Kentico.Xperience.UMT	Core migration tool
utils/Kentico.Xperience.UMT.DocUtils	Used to generate documentation in the repository
examples/Kentico.Xperience.UMT.Example.AdminApp
examples/Kentico.Xperience.UMT.Example.Console
examples/Kentico.Xperience.UMT.Example.Examples

Contributing

To see the guidelines for Contributing to Kentico open source software, please see Kentico's CONTRIBUTING.md for more information and follow the Kentico's CODE_OF_CONDUCT.

Instructions and technical details for contributing to this project can be found in Contributing Setup.

License

Distributed under the MIT License. See LICENSE.md for more information.

Support

This contribution has Full support by 7-day bug-fix policy.

See SUPPORT.md for more information.

Security

For any security issues see Kentico's SECURITY.md.

xperience-by-kentico-universal-migration-tool's Issues

Common Data not able to be adapted into models Language Metadata.

Reusable fields applied to Content Items are not importable through ContentItemLanguageData.ContentItemData since the the column names for the actual content type do not contain those fields and they are contained in the ContentItemCommonData.

Using the example sample say you have a Reusable field schema withe a property name MetadataTitle shown below defined in the ContentItem dictionary. This will fail the check in the GenericAdapter for "Info doesn't contain column with name 'MetadataTitle' - _CustomProperties has invalid key, key SHALL have same name as column in target Info object" since this field exists in the ContentItemCommonData table and is not contained in the ColumnNames for the ContentItemModel loaded when adapting the
LanguageData.

ContentItemSimplifiedModel simplified = new()
    {
        ContentItemGUID = SampleArticleContentItemGuid,
        Name = "SimplifiedModelSample",
        IsSecured = false,
        ContentTypeName = DataClassSamples.ArticleClassSample.ClassName,
        IsReusable = true,
        // channel name is required only for web site content items
        ChannelName = ChannelSamples.SampleChannelForWebSiteChannel.ChannelName,
        // required when content item type is website content item
        PageData = new() {
            ParentGuid = null,
            TreePath = "/simplified-sample",
            PageUrls = [
                new()
                {
                    UrlPath = "en-us/simplified-sample",
                    PathIsDraft = true,
                    LanguageName = ContentLanguageSamples.SampleContentLanguageEnUs.ContentLanguageName!
                },
                new()
                {
                    UrlPath = "en-gb/simplified-sample",
                    PathIsDraft = true,
                    LanguageName = ContentLanguageSamples.SampleContentLanguageEnGb.ContentLanguageName!
                }
            ]
        },
        LanguageData =
        [
            new()
            {
                LanguageName = ContentLanguageSamples.SampleContentLanguageEnUs.ContentLanguageName!,
                DisplayName = "Simplified model sample - en-us",
                VersionStatus = VersionStatus.InitialDraft,
                UserGuid = UserSamples.SampleAdminGuid,
                ContentItemData = new Dictionary<string, object?>
                {
                    ["ArticleTitle"] = "en-US UMT simplified model creation",
                    ["ArticleText"] = "This article is only example of creation UMT simplified model for en-US language",
                    ["RelatedArticles"] = null,
                    ["RelatedFaq"] = null.
                    ["MetadataTitle"] = "Some Value"
                }
            },
            new()
            {
                LanguageName = ContentLanguageSamples.SampleContentLanguageEnGb.ContentLanguageName!,
                DisplayName = "Simplified model sample - en-gb",
                VersionStatus = VersionStatus.Published,
                UserGuid = UserSamples.SampleAdminGuid,
                ContentItemData = new Dictionary<string, object?>
                {
                    ["ArticleTitle"] = "en-GB UMT simplified model creation",
                    ["ArticleText"] = "This article is only example of creation UMT simplified model for en-GB language",
                    ["RelatedArticles"] = null,
                    ["RelatedFaq"] = null.
                    ["MetadataTitleCommon"] = "Some Value"
                }
            }
        ],

ContentItemSimplifiedModel.cs

public class ContentItemLanguageData
{
    [Required]
    public required string LanguageName { get; set; }
    
    [Required]
    public required string DisplayName { get; set; }
    
    public VersionStatus VersionStatus { get; set; } = VersionStatus.InitialDraft;
    
    [Required]
    public required Guid? UserGuid { get; set; }
    
    public Dictionary<string, object?>? ContentItemData { get; set; }
    
    public Dictionary<string, object?>? ContentItemCommonData { get; set; } // Added property to contain common data fields
}

ContentItemSimplifiedAdapter.cs line: 118

var contentItemCommonDataModel = new ContentItemCommonDataModel
            {
                ContentItemCommonDataGUID = contentItemCommonDataInfoGuid ?? Guid.NewGuid(),
                ContentItemCommonDataContentItemGuid = contentItemInfo.ContentItemGUID,
                ContentItemCommonDataContentLanguageGuid = contentLanguageInfo.ContentLanguageGUID,
                ContentItemCommonDataVersionStatus = languageData.VersionStatus,
                ContentItemCommonDataIsLatest = true,
                ContentItemCommonDataPageBuilderWidgets = null,
                ContentItemCommonDataPageTemplateConfiguration = null,
                CustomProperties = languageData?.ContentItemCommonData ?? [] // Allow custom properties to be adapted into the common data for things like metadata schema
            };

Media Library Import: Folder Missing

Describe the bug
After importing a media library using the MediaLibraryModel, the media library was created with no errors in the console or XbyK site. When navigating to the media library and opening on the XbyK site, a 500 error occurs. Upon digging further into what was expected to be created, the data for the Media Library in the database looks correct but no folder under the /assets/media was created. After manually creating the expected folder, the 500 error was fixed and the media library can be opened on the XbyK site.

To Reproduce
Steps to reproduce the behavior:

1. Run migration tool with populated MediaLibraryModel
2. Open XbyK site
3. Open Content management -> Media libraries
4. Open imported Media Library
5. Get 500 - Internal server error
6. Check folders under /assets/media

Expected behavior
After importing a MediaLibraryModel, the content editor can access the media library to add files.

Screenshots

Library Version
1.0.5

Desktop (please complete the following information):

• OS: Windows
• Browser: Chrome
• Version: 124.0.6367.119

Smartphone (please complete the following information):
N/A

Additional context
N/A

P1 - Support decimal precision in the UMT DataClass model.

Is your feature request related to a problem? Please describe.
Competing systems use decimals for numerical control and allow the content editor to specify multiple decimal places. The XbK provides option to set number of decimal places between 0 and 19. Although UMT accepts the creation of a DataClass as a decimal number, it defaults to 4 decimal places.

Describe the solution you'd like
It would be nice to have an option in UMT FormField model to set custom precision of the decimal data type. I would expect ColumnPrecision property in the UMT model to prevent potential data loss while migrating FormField data for the DataClass.

Subsequent import of the same media files makes them not displayable

Kentico.Xperience.UMT package version - 1.0.1

Reproduction steps:

1. Import one or more media files into Xperience by Kentico instance
2. Load media library interface and make sure you can see these media files
3. Import the same media files again
4. In the media library interface these files will become grey rectangles, trying to open media file by URL /getmedia returns 404 error

What I've discovered, during the subsequent imports FilePath attribute removes media file extension.
I.e. if after the first import media file FilePath was "Images/Main Images/Homepage/solutions-1-638x380.jpg", then after the second import it changes to "Images/Main Images/Homepage/solutions-1-638x380" which breaks the interface to display it.