Importing to Kentico Cloud

Premium feature

The Content Management API requires a Professional plan or higher. See Pricing for more details.

If you have a lot of content and want to move it over to your Kentico Cloud project, you can leverage the Content Management API (CM API) to automate a one-time import. This usually means writing a script or an application that parses the content from its original format (be it a database from another CMS, or an XML, CSV or text file) into JSON and sends it to Kentico Cloud.

At this time, you can only import content items, their language variants and assets.

In this tutorial, we will import a single content item – imagine it as a single step in a longer content migration process. The sample project that comes with every trial account of Kentico Cloud contains a group of Cafe content items. Let's add one more coffee shop using the Content Management API.

Note: This tutorial works with Content Management API v1. If you need to migrate taxonomy groups, the CM API v2 is also available as BETA.

Preparing the structure of your project

Before importing your content you need to prepare the structure of your Kentico Cloud project. At minimum, that means defining the content types of the items you want to import and setting your project's languages.

The sample project already has the Cafe content type and two languages set up.

*Cafe* content type.

Cafe content type.

From the app menu, choose Project settings. Under Project settings, choose Localization to manage your languages.

Configuring your project languages.

Configuring your project languages.

If you plan to organize content with taxonomy, you should prepare the taxonomy groups in advance as well.

Enabling the API for your project

The CM API is disabled by default for new projects and you need to activate it. By activating the CM API, the system will also generate a new API key.

  1. In Kentico Cloud, choose Project settings from the app menu.
  2. Under Development, choose API Keys.
  3. Click the Inactive switch to activate the Content Management API.
  4. Copy the API key.

You will use the API key to authenticate your requests. The API key is generated per project per user and expires after 90 days. For more information see API key scope and validity.

Importing your content

Importing content items is a 2 step process, using 2 separate API requests:

  1. Creating a content item which serves as a wrapper for your content.
  2. Adding content inside a language variant of the content item.

In Kentico Cloud UI, the first step is the equivalent of clicking Create new content item while the second step would translate to filling in the content elements.

Each content item can consist of several localized variants. The content itself is always part of a specific language variant, even if your project only uses one language.

Let's import a single Cafe content item into your project. We assume that the Cafe Content type is already prepared.

1. Creating a content item

To add a content item to your project, send a PUT request to the /items/external-id/<YOUR_ITEM_EXTERNAL_ID> endpoint. In the body of the request, specify these properties:

  • name – string with a display name of the new content item.
  • type – reference to a content type.
  • (Optional) sitemap_locations – array of references to sitemap locations.

In the URL, you also have to specify the external-id – id of the content item defined by you (or the ID it had in the original system).

Use your Content Management API Key in the authorization header of the request.

curl --request PUT \
  --url https://manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/items/external-id/ext-cafe-brno-59713 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
    "name": "Brno",
    "type": {
       "codename": "cafe"
    },
    "sitemap_locations": [
    	{
      	"codename":"cafes"
    	},
    	{
   	 "codename":"europe"
   	}
  ]
}'

See our API Reference for more details on Upserting content items.

Best practice: Upsert by external ID

You can use a simple POST to /items request to Add the content item. But using an UPSERT operation and defining an external ID for your item has numerous advantages and makes the import process much smoother:

  • You can run the same request repeatedly. If the item doesn't exist, it will be created. If it does, it will be updated.
  • You can reference or link to your item, even if it hasn't been imported yet (and has no internal ID or codename). You might have other content items that reference this one in Rich text or Linked items elements. But if you are using external IDs you don't need to worry about the order in which the content items are imported.

Kentico Cloud will generate an internal ID and codename for the content item and include it in the response:

{
  "id":"8ceeb2d8-9676-48ae-887d-47ccb0f54a79",
  "name":"Brno",
  "codename":"brno",
  "type":{
    "id":"fe41ae5a-5fe2-420a-8560-f7d6d3533dc2"
  },
  "sitemap_locations":[
    {
      "id":"a60fe91c-88ea-6990-fe3b-cf8f8504cd33"
    },
    {
      "id":"ef86a740-9e4c-0b33-4275-ae78558e71a7"
    }
  ],
  "external_id": "ext-cafe-brno-59713",
  "last_modified":"2017-11-09T16:51:09.041611Z"
}

If your request fails, you will receive a 400 Bad request response with a specific error message telling you why.

To verify that the (still empty) content item has been added, you have two options:

The created item will show up as **Not translated** inside your project.

The created item will show up as Not translated inside your project.

So far, you have only specified general attributes of the content item such as Name, Content type, External ID and Sitemap locations. In the next step, we will add the actual (localized) content.

2. Adding localized content

To add content in a specific language to your new content item, you need to perform another upsert operation.

In REST, this means sending a PUT request to the endpoint specifying the language variant you want to insert or update. The language variant will contain the values of individual content elements.

In the request URL, you need to specify the content item you are importing to (for example, /items/external-id/ext-cafe-brno-59713) and the language of the variant (for example, /variants/codename/en-US).

The request body must contain a single attribute, the elements object. In this object, you specify only the content elements you want to update. Omitted elements will remain unchanged.

curl --request PUT \
  --url https://manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/items/external-id/ext-cafe-brno-59713/variants/codename/en-US \
  --header 'authorization: Bearer <YOUR_API_KEY>' \
  --header 'content-type: application/json' \
  --data '
  {
  "elements": {
    "street":"Nove Sady 25",
    "city":"Brno",
    "country":"Czech Republic",
    "state":"Jihomoravsky kraj",
    "zip_code":"60200",
    "phone":"+420 444 444 444",
    "email":"brnocafe@kentico.com"
  }
}'

See our API Reference for details on how to Upsert a language variant of a content item.

In the example above, we have used external ID to specify the content item and a codename to specify its language variant. But you can also use their internal IDs or a combination of the two.

The response will include the updated language variant:

{
  "item":{
    "id":"8ceeb2d8-9676-48ae-887d-47ccb0f54a79"
  },
  "elements":{
    "street":"Nove Sady 25",
    "city":"Brno",
    "country":"Czech Republic",
    "state":"Jihomoravsky kraj",
    "zip_code":"60200",
    "phone":"+420 444 444 444",
    "email":"brnocafe@kentico.com",
    "photo": []
  },
  "language":{
    "id":"00000000-0000-0000-0000-000000000000"
  },
  "last_modified":"2017-11-14T09:10:48.4469012Z"
}

If your request fails, you will receive a 400 Bad request response with a specific error message telling you why.

Kentico Cloud assigns an ID to each language in your project. The ID of the default language is always 00000000-0000-0000-0000-000000000000.

To verify that the language variant has been imported, you have two options:

  • Check your content list in Kentico Cloud.
  • List language variants of the item using the Content Management API.

What's next?

In this tutorial, you imported a set of plain text content elements into a new content item. You can use the same process to import any number of more complex content items.