Map content to new structure

Mapping on paper

Before you start writing the mapping logic in code, we recommend you first define the mapping visually. You can do this on digital or analog paper. Visual mapping lets you and other stakeholders see how your existing content fits within the new content model. You’ll see which parts fit and which don’t. If a part doesn’t fit, you can adjust the content model or discard that part if it’s not needed. This lets you find possible gaps in your content model early on.

Example mapping

Check the following diagram to see how an existing structure used for blog posts in one system can be mapped to a content model in Kontent.ai. The Kontent.ai content model in the example is based on the Article content modeling accelerator. Notice that the Blog post’s fields don’t always map one-to-one to the Article’s elements; sometimes, you need to transform the existing content to another format. Text fields can usually be mapped 1:1. For anything more complex, there is often a transformation involved.

Mapping in code

Once you’ve verified everything on paper, you can move to the real thing. To simplify the mapping in code, use the Kontent.ai Migration toolkit. The toolkit handles requests to Management API for you and makes the content migration easier. For example, the toolkit checks for existing assets and content items to ensure they’re referenced correctly.

Install the Migration toolkit

To get started, create a Node.js app and install the Migration toolkit by running the following command in the terminal.

Migration toolkit 101

To migrate your exported content to a Kontent.ai project with the Migration toolkit, you need to:

1. Map your textual and structured content to the MigrationItem objects.
2. Map your binary files to the MigrationAsset objects.
3. Import the mapped content from the MigrationItem and MigrationAsset objects to your Kontent.ai project.

Let’s now see how to map content items and assets.

Map exported content to content items

Kontent.ai stores content in content items. Depending on the number of languages in your project, each content item has one or more content item variants. The Migration toolkit’s MigrationItem represents a single localized variant of a content item. This includes the variant’s metadata and elements. The specific elements depend on the content item’s content type. With each MigrationItem, you can choose to specify content for the content item variant’s latest version, published version, or both. The following example shows how you can map content to a MigrationItem. We recommend using strongly typed models for the MigrationItem objects.

Parse rich text content

Plan for any necessary parsing of your existing rich text content to map it to the HTML5 rich text format supported by Kontent.ai’s Management API. Remember that the rich text editor in Kontent.ai doesn’t support custom visual formatting, such as setting text color or font size, for a reason. If your existing rich text content contains visual formatting, you need to decide whether to remove it or transform it into structured content. We recommend removing such custom formatting in most cases. Instead, let your web app or mobile app define how the content should be displayed. It will also mean your content creators can focus on the content instead of the formatting or visual options.

Map binary files to assets

The Migration toolkit’s MigrationAsset represents a single asset. You can reference assets by codenames in multiple MigrationItem objects. Every asset can specify localized asset descriptions for use as alt text.

Putting it together