ContentCon is almost full! Reserve your spot in Austin on 5/23

Join us at ContentCon
Register Now

Migrate your Content using the CLI Migration Plugin

The “Migration” plugin in Contentstack CLI allows developers to automate the content migration process using a custom migration script.

This guide explains how to migrate your content using the CLI migration plugin. We have provided sample migration scripts that developers can use to get started, or you can write your custom scripts.

Developers can validate the deployment before pushing it on production, using a test space to run the migration scripts.

Additional Resource: Refer to our migration GitHub page for more detailed on migration script creation and advanced examples.

Process Overview

The first step is to write a migration script to perform content migration. We have provided sample migration scripts which you can refer to here, or write custom scripts. Furthermore, you can use various methods and SDK instances to make your migration script easy to write and read.

After writing the migration script, use the CLI migration command to migrate your content to the destination branch.

Now lets understand how to migrate content from one branch to another in a stack using the CLI migration command.

Prerequisites

Steps for Execution

  1. Login to Contentstack CLI session
  2. Use the “Migration” command
  1. Login to the Contentstack CLI session

    Firstly you should have the Contentstack CLI installed on your system. In case you haven't yet installed the Contentstack CLI, please follow the steps in the CLI installation guide.

    After installing the CLI on your machine, log in to the CLI session to run the ‘Migration’ command.

    Note: By default, the CLI session will work for the app hosted in the North America region. If you want to switch to the Europe or Azure North America region, follow the steps mentioned in the Set Region command section.

    Now log in to your Contentstack account, by running the following command in your terminal:

    csdx auth:login

    Provide your Contentstack account’s email and password to successfully login to the CLI session.

    Additional Resources: To learn more about the CLI login command, refer to the Login command section.

  2. Use the “Migration” Command

    Once you log in to Contentstack, run the migration command to initiate the procedure.

    To perform the operation you have to write a migration script in your code editor, and mention its file path while using the migration command.

    Tip: We have created a sample migration script for you to get started, which we have discussed further in this guide. Refer to this section, to understand migration scripts and various methods you can use to execute your tasks.

    We assume that you have a migration script ready with you, to migrate the content.

    Now, refer to the following command to start migrating your content.

    Usage:

    csdx cm:migration

    Along with the migration command, users have to define various parameters to successfully migrate the content.

    In order to add a number of options/ parameters in a single line, use the following command:

    Usage:

    Migrate content using Auth token:

    csdx cm:migration -A -n <file_path> -k <api_key>

    OR

    Migrate content using CLI Management token alias:

    csdx cm:migration -a <management_token_alias> -n <file_path> -k <api_key> 

    Options:

    • -A, --authtoken: Add this flag to use the auth token of the current session. After logging in CLI, an auth token is generated for each new session.
    • -a, --management-token-alias: Use this flag to add the management token alias.
    • -k, --api-key: Use this flag to add the API key of your stack.
    • -n, --filePath: Use this flag to provide the path of the file of the migration script.
    • --multi: This flag helps you to migrate multiple content files in a single instance. Mention the folder path where your migration script files are stored.

    Example:

    • csdx cm:migration -A -n “Desktop/file/migration” -k bxxxxxxx
    • csdx cm:migration -a my_token_alias -n “Desktop/file/migration” -k bxxxxxxx

    Migration with Branches

    The migration plugin also supports migration of content from one branch to another.
    If you want to migrate content types from one branch to another, you can use the following command.

    Usage:

    Migrate content using Auth token:

    csdx cm:migration -A -n <file_path> -k <api_key> -b <branch_name>

    OR

    Migrate content using CLI Management token alias:

    csdx cm:migration -a <management_token_alias> -n <file_path> -k <api_key> -b <branch_name>

    Options:

    • -b, --branch: Use this flag to add the branch name where you want to perform the migration.

    Example:

    • csdx cm:migration -A -n “Desktop/file/migration” -k bxxxxxxx -b develop
    • csdx cm:migration -a my_token_alias -n “Desktop/file/migration” -k bxxxxxxx -b develop

    With the migration command stated above, developers can easily migrate content to any branch of the stack.

    In the next section, let’s understand how to create the migration files and use various methods to perform operations in your stack.

Get Started with the Migration Script

Now let’s understand how to create and execute migration scripts using Contentstack CLI. Furthermore, we will discuss various methods for making migration scripts easier to write and more readable.

Create Migration File

First determine the location where the migration script will be written. The migration script file will be exported when the migration command is run, accordingly you can decide the location.

Now, you must specify the file path of the migration script to run the migration process, as mentioned in the migration command.

Developers can use JavaScript to create migration scripts that specify changes to a content model.

Here’s a sample code snippet for you to get started. Copy the sample code and initiate with your migration script.

'use strict';

module.exports = async ({migration, stackSDKInstance}) => {

     // write your scripts here

})

The script file of the code should have a function exported as default, that's the method where the scripts reside.

Note: Developers can alter the code and make changes according to their own requirements.

Let's discuss the objects we used in the above example.

“migration”

This refers to your migration object. The migration object has some predefined methods to perform various tasks like create, edit and so on.
Using these methods you can define the tasks and write other tasks to execute them.

Consider this example, where we have defined a method for creating the Blog content type.

module.exports = async ({ migration, stackSDKInstance }) => {
  const blog = migration
    .createContentType("blog")
    .title("Blog")
    .description('The is Blog content type')
    .isPage(true)
    .singleton(false);  
blog
    .createField("title")
    .display_name("Title")
    .data_type("text")
   .mandatory(true); 
blog
       .createField("url")
       .display_name("URL")
      .data_type("text")
      .mandatory(true); 

 migration.addTask(blog.getTaskDefinition());
};

The last line of the code defines the migration task to execute the method.
Below we have mentioned various methods you can use to easily perform migration.

“stackSDKInstance”

This is a SDK instance initiated with API key and the authentication method is chosen via the CLI.

This is an optional object users can add to customize tasks which are not supported by the migration script.

Currently the migration script only supports content type-related methods. To extend your migration further, you can use this pre-initiated SDK instance to run the file via CLI.

Consider this example where we are creating an entry for the Blog content type

module.exports = async ({migration, stackSDKInstance}) => {

    let createEntryTask = {

    title: 'Create blog entries',

    task: [async (params) => {

      try {

        let entry = {

          title: `Awesome Blog`,

          url: `/awesome-blog`

        }

        await stackSDKInstance.contentType('blog').entry().create({ entry })

      } catch (error) {

        throw error

      }

    }]

  }

  migration.addTask(createEntryTask);

}

Carefully observe the SDK instance we have added to this example which extends our migration script and enables us to perform operations with entries in the content type.

Similar to the previous example, the last line of the code defines the migration task and adds this method to the existing migration tasks list for execution.

Execute the Migration File

After configuring the migration script file, you can proceed to run the file via Contentstack CLI to complete the migration.

Migrate content using Auth token:

csdx cm:migration -A -n <file_path> -k <api_key> 

OR

Migrate content using management token alias:

csdx cm:migration -a <management_token_alias> -n <file_path> -k <api_key>

Options:

  • -b, --branch: Use this flag to add the branch name where you want to perform the migration.

Additional Resource: Check out our GitHub repository for detailed information on the Migration script and various advanced options & examples.

Points to Remember

  1. Currently, the Migration plugin does not support Group fields migration. You can pass a custom schema to the createField method to migrate Group fields.
  2. The Migration plugin does not support Global fields migration. You can migrate Global fields by creating an SDK instance and adding it to content types using the createField method.
  3. Currently, the Migration plugin does not support migration of entries. You can migrate entries by creating an SDK instance to create/ update/ delete entries for your content type.

    Note: For more information check our GitHub repository

Was this article helpful?

Thanks for your feedbackSmile-icon

On This Page

^