Jan Cerman
14 minutes
. 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.
MigrationItem objects.MigrationAsset objects.MigrationItem and MigrationAsset objects to your Kontent.ai project.MigrationItem represents a single localized variant of a content item. This includes the variant’s metadata and elementsMigrationItem. We recommend using strongly typed models for the MigrationItem objects..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.MigrationItem
. All rights reserved.# Add the Migration toolkit to your app
npm i @kontent-ai/migration-toolkit --save-devimport {
MigrationAsset,
MigrationItem,
importAsync,
} from '@kontent-ai/migration-toolkit';
// 1. Map the exported content to MigrationItems
const migrationItems: MigrationItem[] = [];
// 2. Map exported files to MigrationAssets
const migrationAssets: MigrationAsset[] = [];
// 3. Import the mapped data into a Kontent.ai project
await importAsync({
data: {
assets: migrationAssets,
items: migrationItems,
},
environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
apiKey: 'MANAGEMENT_API_KEY',
});
import { MigrationItem } from '@kontent-ai/migration-toolkit';
// MigrationItem defines a localized variant of a content item
const migrationItem: MigrationItem = {
// Variant's metadata
system: {
// Name the content item. Item name is shared for all variants.
name: 'My content item',
// Generate a unique content item codename
codename: 'my_content_item',
// Assign the item to a collection
collection: { codename: 'default' },
// Specify the variant's language
language: { codename: 'en_us' },
// Specify the content type
type: { codename: 'article' },
// Assign the item to a workflow
workflow: { codename: 'default' },
},
versions: [
{
// Put the variant in a specific workflow step
workflow_step: { codename: 'draft' },
elements: {
// Variant's content
// For each element specified by the item's content type, add properties named using element codenames.
// Example: element_codename: elementsBuilder.textElement({ value: 'plaintext' }),
},
},
],
};
import {
MigrationElementModels,
MigrationItem,
MigrationItemSystem,
elementsBuilder,
} from '@kontent-ai/migration-toolkit';
// We recommend you define the structure of your Kontent.ai content type
type LanguageCodenames = 'default' | 'en';
type CollectionCodenames = 'default' | 'global';
type WorkflowCodenames = 'default' | 'custom';
type WorkflowStepCodenames = 'published' | 'archived' | 'draft';
type ContentTypeCodenames = 'movie' | 'actor';
type System<Codename extends ContentTypeCodenames> = MigrationItemSystem<
Codename,
LanguageCodenames,
CollectionCodenames,
WorkflowCodenames
>;
type MovieItem = MigrationItem<
// Defines the elements in the 'Movie' content type defined in Kontent.ai
{
title: MigrationElementModels.TextElement;
plot: MigrationElementModels.RichTextElement;
length: MigrationElementModels.NumberElement;
category: MigrationElementModels.MultipleChoiceElement;
poster: MigrationElementModels.AssetElement;
stars: MigrationElementModels.LinkedItemsElement;
seoname: MigrationElementModels.UrlSlugElement;
released: MigrationElementModels.DateTimeElement;
releasecategory: MigrationElementModels.TaxonomyElement;
},
System<'movie'>,
WorkflowStepCodenames
>;
const movie: MovieItem = {
system: {
name: 'Warrior',
// Ensure a unique codename. Check https://kontent.ai/learn/rules-for-codenames
codename: 'warrior',
collection: { codename: 'default' },
language: { codename: 'default' },
type: { codename: 'movie' },
workflow: { codename: 'default' },
},
// Specify up to 2 versions of the variant - latest and published.
// The latest version can be in any workflow step.
versions: [
{
workflow_step: {
// You can publish the variant during the import, or use any other workflow step
codename: 'published',
},
elements: {
title: elementsBuilder.textElement({ value: 'Warrior' }),
length: elementsBuilder.numberElement({ value: 140 }),
category: elementsBuilder.multipleChoiceElement({
value: [
{
codename: 'drama',
},
{
codename: 'action',
},
],
}),
poster: elementsBuilder.assetElement({
value: [
{
codename: 'warrior_teaser',
},
],
}),
plot: elementsBuilder.richTextElement({
// Check allowed HTML elements in rich text value at https://kontent.ai/learn/rich-text-in-mapi
value: `<h1>Warrior</h1><p>...</p>`,
components: [],
}),
releasecategory: elementsBuilder.taxonomyElement({
value: [
{
codename: 'global_release',
},
],
}),
released: elementsBuilder.dateTimeElement({
value: '2011-09-09T00:00:00Z',
}),
seoname: elementsBuilder.urlSlugElement({
// The value is empty because it's autogenerated based on a dependent text element
mode: 'autogenerated',
value: '',
}),
stars: elementsBuilder.linkedItemsElement({
value: [
{
codename: 'tom_hardy',
},
],
}),
},
},
],
};
const migrationItems: MigrationItem[] = [movie];
import { MigrationAsset } from '@kontent-ai/migration-toolkit';
import { readFileSync } from 'fs'; // Only if using local data
const coverAsset: MigrationAsset = {
// You can read the data from anywhere, not just from the filesystem
binary_data: readFileSync('./movies/posters/warrior.jpg'),
// Ensure a unique asset codename. Check https://kontent.ai/learn/rules-for-codenames
// This codename is used to reference the asset in the MigrationItem object
codename: 'warrior_teaser',
// Name the binary file linked to the asset
filename: 'warrior_teaser.jpg',
// Name the asset
title: 'Warrior cover',
// (Optional) Asign the asset to a collection
collection: {
codename: 'default',
},
// (Optional) Specify localized asset descriptions
descriptions: [
{
language: {
codename: 'default',
},
description: 'Poster for Warrior movie',
},
],
};
const migrationAssets: MigrationAsset[] = [coverAsset];