Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough
Aug 27 2018
Aug 27

Upgrading involves shifting lots of files and content from one site to another. Although there are a number of modules to help you migrate to and in Drupal, the process can turn out to be messy. 

an hourglass in a white background


Migration of content can have various meanings and the scope of file formats - JSON, CSV, spreadsheet or text files - is also important.

In this article, I am going to demonstrate the migration of taxonomy terms using CSV files to Drupal 8. Thanks to Drupal’s entity-based system, the process of migration is more or less similar for all kinds of entities. Once you master the migration process, you can easily migrate nodes, users, vocabularies and custom entity data.

You can use various modules for migration to Drupal 8

Drupal 8 core provides the Migrate and Migrate Drupal modules which are useful when migrating from Drupal 6/7 to Drupal 8. In other cases, we have to use contributed modules. Install Migrate Plus which provides a powerful API for data migration from CSV and spreadsheets and is one of the foremost dependencies.

We will take a sample use case of the States list where our taxonomy terms will be the States' list. Let's get started.

Read Upgrade to Drupal 8 | Complete Migration Guide

Installation

  • Download the Migrate Source CSV module and install it on your Drupal website. Use Composer to install all the required dependencies.
composer require ‘drupal/migrate_source_csv:^2.2’
  • Enable the module from Extend menu or Drush Command. 
$ drush en migrate_tools

$ drush en migrate_source_csv
  • In this example, I am going to migrate the USA States data. I have already created a vocabulary as ‘States’ with fields Name (Default Field in Taxonomy) and State Code (the abbreviation).
     
  • Prepare a CSV file with Headers containing Fields Name and also add an ID field which will act as a unique identifier and can also be later used in migration in case States vocabulary is used by a reference field. Here is the CSV which I have prepared:
     

    ID

    State

    Abbreviation

    1

    Alabama

    AL

    2

    Alaska

    AK

    3

    Arizona

    AZ

    4

    California

    CA

    5

    Colorado

    CO

    and so on.
     
  • Next and the most important step is to write a migration plugin which is a .yml file describing the mapping between data in CSV and Drupal Fields. 

    Here is the migration plugin which I wrote:

    id: state_data
    class: null
    field_plugin_method: null
    cck_plugin_method: null
    migration_tags:
      - 'USA States'
    migration_group: default
    label: 'State migration from CSV'
    source:
      plugin: csv
      path: 'public://USAStates.csv'
      header_row_count: 1
      keys:
        - id
      column_names:
        -
          id: id
        -
          title: state
        -
          abbreviation: abbreviation
    process:
      name: title
      field_abbreviation: abbreviation
    destination:
      plugin: 'entity:taxonomy_term'
      default_bundle: state
    migration_dependencies: null
    
    I have provided a Migration ‘id’, ‘class’, ‘field_plugin_method’, ‘cck_plugin_method’. ID acts as a unique identifier for the migration process. Rest of keys mentioned above aren’t needed in this migration.

    Other keys and their importance:
     

    • Migration Tags: These are displayed as a description in migration UI.
       
    • Migration Group: It is an important field in case you have various migration processes. I have used the default group for this migration.
       
    • Label: It is also a description field for the migration displayed in Migration UI.
       
    • Source: It is the important key and we provide type of plugin i.e CSV in our case, path of our CSV file, Header Row Count so that migration API is able to distinguish between Data and Labels, Key i.e the unique identifier in CSV file.

      Next, we have a mapping of columns in CSV with temporary identifiers which are used in process key. Process key defines mapping with Drupal field and a temporary identifier in format (Drupal Field: Temporary Identifier).
       

    • Destination: This key is used to provide the target entity and bundle if any. Since we are migrating terms data so I have used ‘taxonomy_term’ and bundle ‘state’.
       
  • Once you have created the plugin, it is time to inform the system about. Migration plugin can be imported via Single Config Import menu (/admin/config/development/configuration/single/import). Paste your plugin with config type ‘Migration’ and press import.single configuration, selecting migration as configuration type and code added in the next block
  • Once you have imported the migration plugin you can run the migration process via UI or drush command.

    UI: Go to /admin/structure/migrate and under the list migration menu, you can execute the migration process for the respective migration type.

    Drush: Enter the drush command ‘drush mi state_data’ where state_data is the unique ID of the state's migration.

  • Once the migration process is complete all the Terms are created and the abbreviation field is populated as well.

  • You can rollback, resume and stop migration from Migration UI as well in case something goes wrong or you have some extra data to migrate later on. 

  • In case you have to do any changes in Plugin after importing it, you will first have to export its config file from (admin/config/development/configuration/single/export) and then import it again. 
     

    list of migrated terms and the heading as states

    And it is done!

That is how you can migrate content from a CSV file to Drupal 8. Drop a comment below in case of a query. 

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web