Go to main content

Migrate Kentico CMS pages data to Kentico Kontnet

In this article, you'll learn what it takes to migrate your page data from Kentico CMS to Kentico Kontent using the Migration tool.

Migrate Kentico CMS pages data to Kentico Kontnet

Kentico Kontent has learned how to write data using POST requests. The Content Management API that makes it possible is a very granular API endpoints network. To import a single content item, you are required to make multiple requests. One request has to be made to create a content item wrapper and more additional ones for each language variant. Such a design makes the API robust. However, it is too composite for ordinary tasks like a straightforward bulk data import from whatever source.

The answer to this issue is the Migration tool I have created in co-operation with Jan Lenoch from Kentico. It makes it possible to import data in JSON or CSV formats to Kentico Kontent. In the readme file of the tool repository, you can get all the technical details about the import process. In this article, I would like to share a step by step tutorial on how to migrate pages data from Kentico CMS to Kentico Kontent in a specific scenario.

The scenario

In my Kentico CMS instance, I have articles. I intend to migrate them to a Kentico Kontent project.

Prepare the Kentico Kontent project

I have two cultures en-US and es-ES in Kentico CMS so that I need to create them manually in the Kentico Kontnet project as well.

Articles in Kentico CMS are based on a page type with multiple fields. In the Kentico Kontent project, I have to create a content type with fields that I want to map to those in Kentico CMS.

In Kentico Kontent, I have to enable the Content Management API and the Delivery API.

At this stage, the Kentico Kontent project is ready to receive data from Kentico CMS.

Prepare migration data 

I will migrate the data using the Migration tool in JSON format. The migration data must follow the predefined JSON structure.

To get an idea how the structure should look like I can use the Migration tool to generate a blueprint. I use the tool here: https://migration-tool-kentico-cloud.herokuapp.com/ or run it locally from the repository. In the Project settings area, I fill in Project ID. Then, available content models populate in the Content model selector. I choose Article and hit the Generate blueprint button.

In Kentico CMS, I need to fill the blueprint with real page data. I can do that by using the Custom response repeater web part which is a custom web part and have to be imported into Kentico CMS.

I create a new page in Kentico CMS and place the web part into it.

In web part properties I pick the page type and path of the articles. Also, I fill in the "Content before" and "Content after" fields.

  • Content before: { "items": [
  • Content after: ]}

The crucial part is the transformation which will define the structure of the JSON object I will import into the Kentico Kontent project. In my case, the transformation is of type Text/XML.

  "item": {
    "name": "{% ArticleTitle %}",
    "type": {
    "codename": "article"
"external_id": "{% DocumentId %}"
"variants": [{% 
  foreach (page in Documents[NodeAliasPath].CultureVersions) {
    result+="{\"language\":{\"codename\":\""+ page.DocumentCulture +"\"},\"elements\":{\"summary\": \"" + page.ArticleSummary +"\", \"text\":\""+ page.ArticleText.Replace("\n", "").Replace("\r", "").Replace("\t", "").Replace("\"","\\\"") + "\", \"date\":\""+ FormatDateTime(page.DocumentCreatedWhen, "yyyy-MM-ddTHH:mm:ssZ") + "\"}},";
}{% DataItemCount - DataItemIndex == 1 ? "" : "," %}

Properties of the item object are pretty straightforward. However, the variants array needs some more explanation. The array will store content for all language variants. To repeat them I use the following loop:

foreach (page in Documents[NodeAliasPath].CultureVersions) {};

In the loop, I compose objects and each of them stores language codename: \"language\":{\"codename\":\""+ page.DocumentCulture +"\"}
And elements:

  •  Summary: \"summary\": \"" + page.ArticleSummary +"\"
  • Text: \"text\":\""+ page.ArticleText.Replace("\n", "").Replace("\r", "").Replace("\t", "").Replace("\"","\\\"") + "\"
  • Date: \"date\":\""+ FormatDateTime(page.DocumentCreatedWhen, "yyyy-MM-ddTHH:mm:ssZ") + "\"

The text property is represented by the Rich text content element in Kentico Kontent. It is intended to store HTML markup with a very restricted structure. If you import content from the Kentico CMS WYSIWYG you will have to fix the markup manually to fit that structure. In the exmaple above I apply multiple Replaces to get rid of whitespace and escape the " character. Please note, the sitemap_locations and external_id properties are optional.

When the transformation and web part is set up, I visit the page in the live site mode and copy the output to the clipboard.

Migrate data

Now, I visit the Migration tool here: https://migration-tool-kentico-cloud.herokuapp.com/ or run it locally from the repository

In the Project settings area, I fill in Project ID and relevant Content Management API key of my Kentico Kontent project. In the Import data area, I paste the JSON object obtained from Kentico CMS.

Then I hit the Import data button and watch the migration process in the Logs area. When the migration process is successful, ids and codenames of imported items appear in the Import data area. Also, I can see the new items in the Kentico Kontent Content inventory.

When the process fails the Logs area gives you a hint of what causes the issue.

Final thoughts

The Migration tool is capable of importing data into Kentico Kontent from whatever source. However, the source should provide the data structure that the Migration tool can read. In this article, we have learned how to configure Kentico CMS to get page data in the required structure.

Further reading

all posts
  • Kontent.ai

    Migrate Kentico CMS UniGrid data to Kentico Kontent

    In this article, you'll learn what it takes to migrate UniGrid data from Kentico CMS to Kentico Kontent using the Migration tool.

  • Xperience by Kentico

    Open graph meta tags enhanced by Kentico macros

    Social media networks need more information about your content than just an url to be able to display it in their feeds. For such a purpose we put open graph meta tags in the head …

  • Front-end & JavaScript

    Philips Hue experiments

    I created an app for the Anybody hotel that controls Philips Hue lights. However, before I was able to design and implement the app, I researched the possibilities of the technolog…