🚚 Contentful migrations

Describe and execute changes to your content model and transform entry content.

This CLI is currently available in Beta.

Installation

npm install -g contentful-migration

Usage

Usage as a cli

contentful-migration --space-id <space id to use> <path to migration description file>

In your migration description file, export a function that accepts the migration object as its argument. For example:

module.exports = function (migration) {
  const dog = migration.createContentType('dog');
  const name = dog.createField('name');
  name.type('Symbol').required(true);
};

Usage as a library

const runMigration = require('contentful-migration/built/bin/cli')
const options = {
  fielPath: '<migration-file-path>',
  spaceId: '<space-id>',
  accessToken: '<access-token>'
}
runMigration(options)

In your migration description file, export a function that accepts the migration object as its argument. For example:

module.exports = function (migration) {
  const dog = migration.createContentType('dog');
  const name = dog.createField('name');
  name.type('Symbol').required(true);
};

Setup

You need to export the following environment variables for the CLI to work:

• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN – The personal access token for accessing the CMA.
• HTTP_PROXY or http_proxy (optional) – The settings for the HTTP proxy in the shape of http://[user:password@]<host>[:port].
• HTTPS_PROXY or https_proxy (optional) – The settings for the HTTPS proxy in the shape of https://[user:password@]<host>[:port].

If you are using the Contentful CLI these will be automatically picked up from your ~/.contentfulrc.json configuration file.

Please note that the environment variables will take precedence over the ~/.contentfulrc.json configuration.

Chaining vs Object notation

All methods described below can be used in two flavors:

1. The chained approach:

   const author = migration.createContentType('author')
     .name('Author')
     .description('Author of blog posts or pages')

2. 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.

Reference documentation

migration

The main interface for creating and editing content types.

createContentType(id[, opts]) : ContentType

Creates 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.

editContentType(id[, opts]) : ContentType

Edits 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 ID

• from : array (required) – Array of the source field IDs

• to : array (required) – Array of the target field IDs

• 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. from == {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 : boolean (optional) – If true, the transformed entries will be published. If false, both will remain in draft state (default true)

Example

migration.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 transformed

  The 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 : boolean (optional) – If true, both the source and the derived entries will be published. If false, both will remain in draft state (default true)

Example

migration.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.

Content type

For a comprehensive guide to content modelling, please refer to this guide.

createField(id[, opts]) : Field

Creates 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)
  • Integer
  • Number
  • Date
  • Boolean
  • Object
  • Location
  • Array (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]) : Field

Edits the field of provided id.

id : string – The ID of the field to delete.

opts : Object – Same as createField listed above.

deleteField(id) : void

Shorthand 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) : void

Changes the field's ID.

currentId : string – The current ID of the field. newId : string – The new ID for the field.

changeEditorInterface (fieldId, widgetId[, settings]) : void

Changes the editor interface of given field's ID.

fieldId : string – The ID of the field.

widgetId : string – The new widget ID for the field. See the editor interface documentation for a list of available widgets.

settings : Object – Widget settings, with the following options:

• 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 stringss “12” or “24” (default).

Field

The field object has the same methods as the properties listed in the ContentType.createField method.

Validation errors

You can learn more from the possible validation errors here.

Examples

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:

export CONTENTFUL_MANAGEMENT_ACCESS_TOKEN=your-token
export SPACE_ID=your-space-id
contentful-migration --space-id $SPACE_ID 01-angry-dog.js
contentful-migration --space-id $SPACE_ID 02-friendly-dog.js
contentful-migration --space-id $SPACE_ID 03-long-example.js
contentful-migration --space-id $SPACE_ID 04-steps-errors.js
contentful-migration --space-id $SPACE_ID 05-plan-errors.js
contentful-migration --space-id $SPACE_ID 06-delete-field.js
contentful-migration --space-id $SPACE_ID 07-display-field.js

Programmatic Usage

To use the CLI without the manual confirmation step (e.g. in a CI environment), you can pass the --yes (or just -y) flag:

contentful-migration --yes --space-id YOUR_TOKEN ./your-migration.js

Support

If you have a problem with this tool, please file an issue here on Github.

If you have other problems with Contentful not related to this library, you can contact Customer Support.

License

MIT