Go to main content

Migrate Kentico CMS pages data to Kentico Cloud

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

Migrate Kentico CMS pages data to Kentico Cloud

Kentico Cloud 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 possible to import data in JSON or CSV formats to Kentico Cloud. 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 Cloud on a specific scenario.

The scenario

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

Prepare the Kentico Cloud project

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

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

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

At this stage, the Kentico Cloud 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 pages 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 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 Cloud project. In my case, the transformation is of type Text/XML.

{
  "item": {
    "name": "{% ArticleTitle %}",
    "type": {
    "codename": "article"
  },
"external_id": "{% DocumentId %}"
},
"variants": [{% 
  result="";
  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") + "\"}},";
  };
  result.TrimEnd(",");
#%}]
}{% 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 Cloud. 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 Cloud 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 Cloud Content inventory.

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

Final thoughts

The Migration tool is capable of importing data into Kentico Cloud 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 pages data in the required structure.

Milan Lund

is a freelance web developer and a proud Basenji owner. His specialties are Kentico CMS/EMS and Kentico Cloud.

Further reading

all posts
  • Kentico Cloud

    Migrate Kentico CMS UniGrid data to Kentico Cloud

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

  • Kentico CMS & EMS

    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 …

  • Kentico CMS & EMS

    Reload Javascript after postback in Kentico

    For any kind of form web parts, I like using update panel to avoid full page reload when the form is submitted. In such situation, a postback is invoked. When you execute a Javascr…