contentful-migration
Advanced tools
Describe and execute changes to your content model and transform entry content.
What is Contentful?
Contentful provides content infrastructure for digital teams to power websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship their products faster.
migration
context
createField(id[, opts]) : FieldeditField(id[, opts]) : FielddeleteField(id) : voidchangeFieldId (currentId, newId) : voidmoveField (id) : MovableFieldchangeFieldControl (fieldId, widgetNamespace, widgetId[, settings]) : voidresetFieldControl (fieldId) : voidcopyFieldControl (sourceFieldId, destinationFieldId) : voidaddSidebarWidget (widgetNamespace, widgetId[, settings, insertBeforeWidgetId]) : voidupdateSidebarWidget (widgetNamespace, widgetId, settings) : voidremoveSidebarWidget (widgetNamespace, widgetId) : voidresetSidebarToDefault () : voidconfigureEntryEditor (widgetNamespace, widgetId[, settings]) : voidconfigureEntryEditors (EntryEditor[]) : voidresetEntryEditorToDefault () : voidnpm install contentful-migration
We moved the CLI version of this tool into our Contentful CLI. This allows our users to use and install only one single CLI tool to get the full Contentful experience.
Please have a look at the Contentful CLI migration command documentation to learn more about how to use this as command line tool.
const { runMigration } = require('contentful-migration')
const options = {
filePath: '<migration-file-path>',
spaceId: '<space-id>',
accessToken: '<access-token>'
}
runMigration(options)
.then(() => console.log('Migration Done!'))
.catch((e) => console.error(e))
In your migration description file, export a function that accepts the migration object as its argument. For example:
module.exports = function (migration, context) {
const dog = migration.createContentType('dog');
const name = dog.createField('name');
name.type('Symbol').required(true);
};
| Name | Default | Type | Description | Required |
|---|---|---|---|---|
| filePath | string | The path to the migration file | true | |
| spaceId | string | ID of the space to run the migration script on | true | |
| environmentId | 'master' | string | ID of the environment within the space to run the | false |
| accessToken | string | The access token to use | true | |
| yes | false | boolean | Skips any confirmation before applying the migration,script | false |
| requestBatchSize | 100 | number | Limit for every single request | false |
| headers | object | Additional headers to attach to the requests | false |
All methods described below can be used in two flavors:
The chained approach:
const author = migration.createContentType('author')
.name('Author')
.description('Author of blog posts or pages')
The object approach:
const author = migration.createContentType('author', {
name: 'Author',
description: 'Author of blog posts or pages'
})
While both approaches work, it is recommended to use the chained approach since validation errors will display context information whenever an error is detected, along with a line number. The object notation will lead the validation error to only show the line where the object is described, whereas the chained notation will show precisely where the error is located.
migrationThe main interface for creating and editing content types and tags.
createContentType(id[, opts]) : ContentTypeCreates a content type with provided id and returns a reference to the newly created content type.
id : string – The ID of the content type.
opts : Object – Content type definition, with the following options:
name : string – Name of the content type.description : string – Description of the content type.displayField : string – ID of the field to use as the display field for the content type. This is referred to as the "Entry title" in the web application.editContentType(id[, opts]) : ContentTypeEdits an existing content type of provided id and returns a reference to the content type.
Uses the same options as createContentType.
deleteContentType(id)Deletes the content type with the provided id and returns undefined. Note that the content type must not have any entries.
transformEntries(config)For the given content type, transforms all its entries according to the user-provided transformEntryForLocale function. For each entry, the CLI will call this function once per locale in the space, passing in the from fields and the locale as arguments.
The transform function is expected to return an object with the desired target fields. If it returns undefined, this entry locale will be left untouched.
config : Object – Content transformation definition, with the following properties:
contentType : string (required) – Content type IDfrom : array (required) – Array of the source field IDsto : array (required) – Array of the target field IDstransformEntryForLocale : function (fields, locale): object (required) – Transformation function to be applied.
fields is an object containing each of the from fields. Each field will contain their current localized values (i.e. fields == {myField: {'en-US': 'my field value'}})locale one of the locales in the space being transformed
The return value must be an object with the same keys as specified in to. Their values will be written to the respective entry fields for the current locale (i.e. {nameField: 'myNewValue'}). If it returns undefined, this the values for this locale on the entry will be left untouched.shouldPublish : bool | 'preserve' (optional) – Flag that specifies publishing of target entries, preserve will keep current states of the source entries (default 'preserve')transformEntries Examplemigration.transformEntries({
contentType: 'newsArticle',
from: ['author', 'authorCity'],
to: ['byline'],
transformEntryForLocale: function (fromFields, currentLocale) {
if (currentLocale === 'de-DE') {
return;
}
const newByline = `${fromFields.author[currentLocale]} ${fromFields.authorCity[currentLocale]}`;
return { byline: newByline };
}
});
For the complete version, please refer to this example.
deriveLinkedEntries(config)For each entry of the given content type (source entry), derives a new entry and sets up a reference to it on the source entry. The content of the new entry is generated by the user-provided deriveEntryForLocale function.
For each source entry, this function will be called as many times as there are locales in the space. Each time, it will be called with the from fields and one of the locales as arguments.
The derive function is expected to return an object with the desired target fields. If it returns undefined, the new entry will have no values for the current locale.
config : Object – Entry derivation definition, with the following properties:
contentType : string (required) – Source content type ID
derivedContentType : string (required) – Target content type ID
from : array (required) – Array of the source field IDs
toReferenceField : string (required) – ID of the field on the source content type in which to insert the reference
derivedFields : array (required) – Array of the field IDs on the target content type
identityKey: function (fields): string (required) - Called once per source entry. Returns the ID used for the derived entry, which is also used for de-duplication so that multiple source entries can link to the same derived entry.
fields is an object containing each of the from fields. Each field will contain their current localized values (i.e. fields == {myField: {'en-US': 'my field value'}})deriveEntryForLocale : function (fields, locale): object (required) – Function that generates the field values for the derived entry.
fields is an object containing each of the from fields. Each field will contain their current localized values (i.e. fields == {myField: {'en-US': 'my field value'}})locale one of the locales in the space being transformedThe return value must be an object with the same keys as specified in derivedFields. Their values will be written to the respective new entry fields for the current locale (i.e. {nameField: 'myNewValue'})
shouldPublish : bool (optional) – Flag that specifies publishing of target entries. (default true)
deriveLinkedEntries(config) Examplemigration.deriveLinkedEntries({
contentType: 'dog',
derivedContentType: 'owner',
from: ['owner'],
toReferenceField: 'ownerRef',
derivedFields: ['firstName', 'lastName'],
identityKey: async (fromFields) => {
return fromFields.owner['en-US'].toLowerCase().replace(' ', '-');
},
shouldPublish: true,
deriveEntryForLocale: async (inputFields, locale) => {
if (locale !== 'en-US') {
return;
}
const [firstName, lastName] = inputFields.owner[locale].split(' ');
return {
firstName,
lastName
};
}
});
For the complete version of this migration, please refer to this example.
transformEntriesToType(config)For the given (source) content type, transforms all its entries according to the user-provided transformEntryForLocale function into a new entry of a specific different (target) content type. For each entry, the CLI will call the function transformEntryForLocale once per locale in the space, passing in the from fields and the locale as arguments. The transform function is expected to return an object with the desired target fields. If it returns undefined, this entry locale will be left untouched.
config : Object – Content transformation definition, with the following properties:
sourceContentType : string (required) – Content type ID of source entries
targetContentType : string (required) – Targeted Content type ID
from : array (optional) – Array of the source field IDs, returns complete list of fields if not configured
identityKey: function (fields): string (required) - Function to create a new entry ID for the target entry
shouldPublish : bool | 'preserve' (optional) – Flag that specifies publishing of target entries, preserve will keep current states of the source entries (default false)
updateReferences : bool (optional) – Flag that specifies if linking entries should be updated with target entries (default false)
removeOldEntries : bool (optional) – Flag that specifies if source entries should be deleted (default false)
transformEntryForLocale : function (fields, locale): object (required) – Transformation function to be applied.
fields is an object containing each of the from fields. Each field will contain their current localized values (i.e. fields == {myField: {'en-US': 'my field value'}})locale one of the locales in the space being transformedThe return value must be an object with the same keys as specified in the targetContentType. Their values will be written to the respective entry fields for the current locale (i.e. {nameField: 'myNewValue'}). If it returns undefined, this the values for this locale on the entry will be left untouched.
transformEntriesToType Exampleconst MurmurHash3 = require('imurmurhash');
migration.transformEntriesToType({
sourceContentType: 'dog',
targetContentType: 'copycat',
from: ['woofs'],
shouldPublish: false,
updateReferences: false,
removeOldEntries: false,
identityKey: function (fields) {
const value = fields.woofs['en-US'].toString();
return MurmurHash3(value).result().toString();
},
transformEntryForLocale: function (fromFields, currentLocale) {
return {
woofs: `copy - ${fromFields.woofs[currentLocale]}`
};
}
});
For the complete version of this migration, please refer to this example.
createTag(id[, opts])Creates a tag with provided id and returns a reference to the newly created tag.
id : string – The ID of the tag.
opts : Object – Tag definition, with the following options:
name : string – Name of the tag.editTag(id[, opts])Edits an existing tag of provided id and returns a reference to the tag.
Uses the same options as createTag.
deleteTag(id)Deletes the tag with the provided id and returns undefined. Note that this deletes the tag even if it is still attached to entries or assets.
setTagsForEntries(config)For the given content type, updates the tags that are attached to its entries according to the user-provided setTagsForEntry function. For each entry, the CLI will call this function once, passing in the from fields, link objects of all tags that already are attached to the entry and link objects of all tags available in the environment. The setTagsForEntry function is expected to return an array with link objects for all tags that are to be added to the entry. If it returns undefined, the entry will be left untouched.
config : Object – Content transformation definition, with the following properties:
contentType : string (required) – Content type IDfrom : array (required) – Array of the source field IDssetTagsForEntry : function (entryFields, entryTags, apiTags): array (required) – Transformation function to be applied.
entryFields is an object containing each of the from fields.entryTags is an array containing link objects of all tags
already attached to the entry.apiTags is an array containing link objects of all tags
available in the environment.setTagsForEntries Examplemigration.createTag('department-sf').name('Department: San Francisco')
migration.createTag('department-ldn').name('Department: London')
const departmentMapping = {
'san-francisco': 'department-sf',
'london': 'department-ldn'
}
migration.setTagsForEntries({
contentType: 'news-article',
from: ['department'],
setTagsForEntry: (entryFields, entryTags, apiTags) => {
const departmentField = entryFields.department['en-US']
const newTag = apiTags.find((tag) => tag.sys.id === departmentMapping[departmentField])
return [
...entryTags,
newTag,
]
}
})
contextThere may be cases where you want to use Contentful API features that are not supported by the migration object. For these cases you have access to the internal configuration of the running migration in a context object.
module.exports = async function (migration, { makeRequest, spaceId, accessToken }) {
const contentType = await makeRequest({
method: 'GET',
url: `/content_types?sys.id[in]=foo`
});
const anyOtherTool = new AnyOtherTool({ spaceId, accessToken })
};
makeRequest(config)The function used by the migration object to talk to the Contentful Management API. This can be useful if you want to use API features that may not be supported by the migration object.
config : Object - Configuration for the request based on the Contentful management SDK
method : string – HTTP methodurl : string - HTTP endpointmodule.exports = async function (migration, { makeRequest }) {
const contentType = await makeRequest({
method: 'GET',
url: `/content_types?sys.id[in]=foo`
})
};
spaceId : stringThe space ID that was set for the current migration.
accessToken : stringThe access token that was set for the current migration.
For a comprehensive guide to content modelling, please refer to this guide.
createField(id[, opts]) : FieldCreates a field with provided id.
id : string – The ID of the field.
opts : Object – Field definition, with the following options:
name : string (required) – Field name.
type : string (required) – Field type, amongst the following values:
Symbol (Short text)Text (Long text)IntegerNumberDateBooleanObjectLocationRichTextArray (requires items)Link (requires linkType)items : Object (required for type 'Array') – Defines the items of an Array field.
Example:
items: {
type: 'Link',
linkType: 'Entry',
validations: [
{ linkContentType: [ 'my-content-type' ] }
]
}
linkType : string (required for type 'Link') – Type of the referenced entry.
Can take the same values as the ones listed for type above.
required : boolean – Sets the field as required.
validations : Array – Validations for the field.
Example:
validations: [
{ in: [ 'Web', 'iOS', 'Android' ] }
]
See The CMA documentation for the list of available validations.
localized : boolean – Sets the field as localized.
disabled : boolean – Sets the field as disabled, hence not editable by authors.
omitted : boolean – Sets the field as omitted, hence not sent in response.
deleted : boolean – Sets the field as deleted. Requires to have been omitted first.
You may prefer using the deleteField method.
editField(id[, opts]) : FieldEdits the field of provided id.
id : string – The ID of the field to delete.
opts : Object – Same as createField listed above.
deleteField(id) : voidShorthand method to omit a field, publish its content type, and then delete the field. This implies that associated content for the field will be lost.
id : string – The ID of the field to delete.
changeFieldId (currentId, newId) : voidChanges the field's ID.
currentId : string – The current ID of the field.
newId : string – The new ID for the field.
moveField (id) : MovableFieldMove the field (position of the field in the web editor)
id: string - The ID of the field to move
.moveField(id) returns a movable field type which must be called with a direction function:
.toTheTop().toTheBottom().beforeField(fieldId).afterField(fieldId)Example:
module.exports = function (migration) {
const food = migration.editContentType('food');
food.createField('calories')
.type('Number')
.name('How many calories does it have?');
food.createField('sugar')
.type('Number')
.name('Amount of sugar');
food.createField('vegan')
.type('Boolean')
.name('Vegan friendly');
food.createField('producer')
.type('Symbol')
.name('Food producer');
food.createField('gmo')
.type('Boolean')
.name('Genetically modified food');
food.moveField('calories').toTheTop();
food.moveField('sugar').toTheBottom();
food.moveField('producer').beforeField('vegan');
food.moveField('gmo').afterField('vegan');
};
changeFieldControl (fieldId, widgetNamespace, widgetId[, settings]) : voidChanges control interface of given field's ID.
fieldId : string – The ID of the field.
widgetNamespace : string – The namespace of the widget, one of the following values:
builtin (Standard widget)extension (Custom UI extension)widgetId : string – The new widget ID for the field. See the editor interface documentation for a list of available widgets.
settings : Object – Widget settings and extension instance parameters. Key-value pairs of type (string, number | boolean | string). For builtin widgets, the the following options are available:
helpText : string – This help text will show up below the field.trueLabel : string (only for fields of type boolean) – Shows this text next to the radio button that sets this value to true. Defaults to “Yes”.falseLabel : string (only for fields of type boolean) – Shows this text next to the radio button that sets this value to false. Defaults to “No”.stars : number (only for fields of type rating) – Number of stars to select from. Defaults to 5.format : string (only for fields of type datePicker) – One of “dateonly”, “time”, “timeZ” (default). Specifies whether to show the clock and/or timezone inputs.ampm : string (only for fields of type datePicker) – Specifies which type of clock to use. Must be one of the strings “12” or “24” (default).bulkEditing : boolean (only for fields of type Array) – Specifies whether bulk editing of linked entries is possible.resetFieldControl (fieldId) : voidfieldId : string – The ID of the field.
copyFieldControl (sourceFieldId, destinationFieldId) : voidsourceFieldId : string – The ID of the field to copy the control setting from.
destinationFieldId : string – The ID of the field to apply the copied control setting to.
addSidebarWidget (widgetNamespace, widgetId[, settings, insertBeforeWidgetId]) : voidAdds a builtin or custom widget to the sidebar of the content type.
widgetNamespace: string – The namespace of the widget, one of the following values:
sidebar-builtin (Standard widget, default)extension (Custom UI extension)widgetId : string – The ID of the builtin or extension widget to add.
settings : Object – Instance settings for the widget. Key-value pairs of type (string, number | boolean | string)
insertBeforeWidgetId : Object – Insert widget above this widget in the sidebar. If null, the widget will be added to the end.
updateSidebarWidget (widgetNamespace, widgetId, settings) : voidUpdates the configuration of a widget in the sidebar of the content type.
widgetNamespace: string – The namespace of the widget, one of the following values:
sidebar-builtin (Standard widget, default)extension (Custom UI extension)widgetId : string – The ID of the builtin or extension widget to add.
settings : Object – Instance settings for the widget. Key-value pairs of type (string, number | boolean | string)
removeSidebarWidget (widgetNamespace, widgetId) : voidRemoves a widget from the sidebar of the content type.
widgetNamespace: string – The namespace of the widget, one of the following values:
sidebar-builtin (Standard widget, default)extension (Custom UI extension)widgetId : string – The ID of the builtin or extension widget to remove.
resetSidebarToDefault () : voidResets the sidebar of the content type to default.
configureEntryEditor (widgetNamespace, widgetId[, settings]) : voidSets the entry editor to specified widget.
widgetNamespace: string – The namespace of the widget.
widgetId : string – The ID of the builtin or extension widget to add.
settings : Object – Instance settings for the widget. Key-value pairs of type (string, number | boolean | string). Optional.
configureEntryEditors (EntryEditor[]) : voidAs opposed to configureEntryEditor which only sets one editor, this sets a list of editors to the current editor interface of a content-type.
Each EntryEditor has the following properties:
widgetNamespace: string – The namespace of the widget (i.e: app, extension or builtin-editor).widgetId : string – The ID of the builtin, extension or app widget to add.settings : Object – Instance settings for the widget. Key-value pairs of type (string, number | boolean | string). Optional.resetEntryEditorToDefault () : voidResets the entry editor of the content type to default.
The field object has the same methods as the properties listed in the ContentType.createField method.
You can learn more from the possible validation errors here.
You can check out the examples to learn more about the migrations DSL. Each example file is prefixed with a sequence number, specifying the order in which you're supposed to run the migrations, as follows:
const runMigration = require('contentful-migration/built/bin/cli').runMigration
const options = {
spaceId: '<space-id>',
accessToken: '<access-token>',
yes: true
}
const migrations = async () => {
await runMigration({...options, ...{filePath: '01-angry-dog.js'}})
await runMigration({...options, ...{filePath: '02-friendly-dog.js'}})
await runMigration({...options, ...{filePath: '03-long-example.js'}})
await runMigration({...options, ...{filePath: '04-steps-errors.js'}})
await runMigration({...options, ...{filePath: '05-plan-errors.js'}})
await runMigration({...options, ...{filePath: '06-delete-field.js'}})
await runMigration({...options, ...{filePath: '07-display-field.js'}})
}
migrations()
You can use Typescript to write your migration files using ts-node! First npm install --save ts-node typescript,
then run your migration with ts-node:
node_modules/.bin/ts-node node_modules/.bin/contentful-migration -s $CONTENTFUL_SPACE_ID -a $CONTENTFUL_MANAGEMENT_TOKEN my_migration.ts
An example Typescript migration:
import { MigrationFunction } from 'contentful-migration'
// typecast to 'MigrationFunction' to ensure you get type hints in your editor
export = function (migration, { makeRequest, spaceId, accessToken }) {
const dog = migration.createContentType('dog', {
name: 'Dog'
})
const name = dog.createField('name')
name.name('Name')
.type('Symbol')
.required(true)
} as MigrationFunction
Here's how it looks inside VS Code:
rawProxy option to true.runMigration({
proxy: 'https://cat:dog@example.com:1234',
rawProxy: true,
...
})
. Make sure to remove any credential from your code before sharing it.
We appreciate any help on our repositories. For more details about how to contribute see our CONTRIBUTING.md document.
This repository is published under the MIT license.
We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.
FAQs
Migration tooling for contentful
The npm package contentful-migration receives a total of 62,423 weekly downloads. As such, contentful-migration popularity was classified as popular.
We found that contentful-migration demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.