This week we're in Europe for DrupalCon Amsterdam! This is starting to feel suspiciously close to a beta so it is time to dive into Migrate again so you can start working on your new sites with real-world data. Let's begin!

What's up with migrate?

Migrate in the Drupal context means running a migration from the new Drupal 8 site and pulling data from an existing site. It replaces the old upgrade-in-place system that was used in prior versoins of Drupal. So do a fresh install of Drupal 8 and have an old Drupal 6 site on the same host. After you've logged into Drupal 8 you can connect to your Drupal 6 site.

How is Drupal 8 migrate different from Drupal 7 migrate (and migrate_d2d)?

In the older versions of Migrate the process invovled defining your field mappings and manually creating the new content types in the D7 system. This is no longer necessary. Drupal 8 migrations will automatically create the needed content types and establish the mappings between the old and new fields by default. Therefore much less configuration is needed. For times when it is necessary to customizae your migration you can use the included hooks or you can use the configuration schema to use the included plugins with your custom data set. The hooks go further than in D7, allowing you to alter data in the prepareRow stage without having to create a custom migration to deal with the data.

Migrate from Drupal 6? What about from Drupal 7?

Migrate frees us from the need to update each sequential version. You can leafrog versions! With Drupal 6 being close to end-of-life it is important to have a pathway for these users. For this reason, the D6 to D8 path was built first. For Drupal 7: soon. This is now in-progress now that we are finalizing the Drupal 6 code.

Requirements

• Drush! The UI is still in a contrib sandbox, so for now you must use Drush. The latest version - from Github.
• Composer. It is needed to install Drush. Go into the drush folder and run "composer install". Already installed? "composer update"
• D6 Database. Have it on the same host as the new Drupal 8 install.
• D6 Files. Probably a good idea to be on the same host. Can be file path or http(s) address.
• D8 Database. A new, empty database. Use the old Creating the database howto if new to this.
• D8 Files. Check out the git repo... unless of course a beta becomes available. Then use that.

Using Drupal Tools If you do not currently have a Drupal 8 install one route to get there is to use the

[Drupal Tools][4] for your platform. It includes all the software you need and the correct versions. It is available for Linux, Mac, and Windows. If you install the Drupal Tools package it is not necessary to install Git, Drush, or Composer. The installation should be current as it includes a version of Drush which must be up-to-date. So if you had installed Tools before, double check the version if you have any trouble. 

Install Drupal8 Using the database credentials you created, install your new Drupal 8 site. If you need to rebuild your site remember to delete your ENTIRE files folder and old settings.php. Reinstalling without doing this step will cause problems. 

Install Composer / Drush Make sure you have run the Composer installer. You should be able to type 

`which composer` and get a result in your terminal. Check out the latest Drush. Go into the Drush folder and run `composer install`. Next time you `git pull` (or `git fetch`) in the Drush folder, make sure to run `composer update`. 
### Find an isuse to test

*   Go to the Drupal project issue queue and [filter down by Component: migration system, Version: 8.x][5].
*   Pick an issue that is not already fixed.
*   If you are sprinting with lots of people, pick something further down the list so you are not working on the same thing as someone else.
*   Read the posts. If it is easy enough you think you can handle it, post a comment to say you are doing some work on it.
*   Post the results of your tests.
### Time to Migrate Put the manifest.yml file with the migrations you wish to run in your D8 site root. Then go there on the command line and run the following command, using your D6 database credentials. You can install Drupal 8 at this stage. If you do, be sure to enable all of the necessary modules. For example, if you use the Book module, it is not enabled by default, so you should enable it now or your book nodes will simply become a regular content type. When Drupal 8 is no longer in beta the manifest.yml file will not be necessary unless you are doing some custom work. In most cases all that will be necessary is to put in the database credentials and the system will run all the migrations that the system knows about by default. You will find a manifest.yml file attached to many Migrate issues that will enable you to begin the migration. Here is a sample of what I am using... I have added together many different issues and I run them all at the same time: 

*To get the complete list of available migrations run **drush config-list|grep migrate*** `# user

• d6_user
• d6_user_profile_field
• d6_user_profile_field_instance
• d6_user_profile_entity_display
• d6_user_profile_entity_form_display
• d6_profile_values:user
• d6_filter_format
• d6_user_role
• d6_user_picture_entity_display
• d6_user_picture_entity_form_display
• d6_user_picture_file
• d6_user_picture_field
• d6_user_picture_field_instance

  taxonomy

• d6_taxonomy_vocabulary
• d6_taxonomy_settings
• d6_taxonomy_term

  nodes

• d6_node
• d6_node_revision
• d6_node_type
• d6_view_modes
• d6_filter_format
• d6_field_instance_per_form_display
• d6_field_instance_widget_settings
• d6_field_formatter_settings
• d6_field_instance
• d6_field
• d6_field_settings
• d6_node_settings
• d6_cck_field_values:*
• d6_cck_field_revision:*

  taxonomy fields

• d6_term_node_revision
• d6_term_node
• d6_vocabulary_entity_display
• d6_vocabulary_entity_form_display
• d6_vocabulary_field_instance
• d6_vocabulary_field

  blocks

• d6_block
• d6_menu

  custom blocks

• d6_custom_block
• d6_filter_format

  book

• d6_book
• d6_book_settings

  files

• d6_file: source: conf_path: sites/assets destination: source_base_path: destination/base/path destination_path_property: uriNow that you have created a manifest.yml file in the Drupal 8 root directory you can run the migration.drush migrate-manifest --legacy-db-url=mysql://d6user:d6pass@localhost/d6 manifest.ymlIf you are using Drupal Tools (Acquia Dev Desktop), and if you have *also* put your D6 site into Dev Desktop, you will need to specify the port number. You can find your database settings by creating an AcquiaDevDesktop terminal and typing drush status to get the exact settings for your D6 site. The result should look something like this:drush migrate-manifest --legacy-db-url=mysql://drupaluser:@127.0.0.1:33067/drupal_6 manifest.yml` Note that the database user for D6 is called "drupaluser" and it uses the local IP address and port number rather than the host name. Again, run drush status if you are having trouble connecting to verify these values.

  Results After you have run the migration check your work. Did things do what you expected? Post the results of your findings to the issue queue you of the item you were working on. Was the result successful? If so, post the result. Did something fail? Post the result. Post your results! Don't be afraid to comment on Drupal.org. If you provide examples of your tests you will help the migration path improve.

  Rolling back (starting over)

  • It is possible to re-run the migration. This can be helpful if you forgot to run a component, or if you have new items in the source site that you would like to add to the Drpual8 site.
  • To completely "roll-back" you really need to reinstall Drupal 8. To do this you must do three things: (1) empty your database, (2) delete settings.php, (3) remove the files folder completely.

    Files

  • Le sigh!* One problem you will run into at the moment is that using drush there is no way to set the path of the files directory from d6. UPDATE: use the new manifest format in the code block shown above to set your file paths. It is the ONLY settings you will need in your manifest file. The other solution is to use the migrate_upgrade contrib module (which will hopefully be part of 8.1). This module provides a URL at /upgrade which allows you to put database settings and file path. It does not let you select which migratiosn to run - they ALL run. So if you must test file migrations, this is the way (for now) but note that it is not as focused as the other testing methods. Currently migrate_upgrade has some bugs! Look at the issue queue for the critical patches until the next update to migrate_upgrade is ready (at the moment the last version of that module dates back to June 2014).

    Going further

  • Join us at IMP meetups. Find out more at groups.drupal.org/imp.
  • Read the Drupal 8 Migrate API documentation.
  • Sprint with us if you are in Amsterdam this week!
  • Participate in IRC at #drupal-migrate.