Migrate 2.6 UI Changes

The Migrate module provides services for migrating data from various sources (other CMS frameworks, external web services, or other Drupal installations) into the local Drupal environment. It has been used to migrate sites such as The Economist, Examiner.com, Stanford Law School, and PayPal and eBay's developer forums (x.com) to Drupal.

Since my previous post on the framework changes in Migrate 2.6, I have released a release candidate. Today I will cover some of the most significant changes in the Migrate UI, for those who have been working with Migrate 2.5 and earlier.

Groups in UI

The first difference you will probably notice in the Migrate UI is in the main dashboard page at admin/content/migrate. Formerly this listed every migration you had defined, but now that we've enhanced group functionality, the first thing you'll see here is a list of your groups. For example, if you have migrate_example enabled:

More on that "Source system" column in the next post...

Clicking on a group name will give you the list of migrations (or "tasks") in the group, which should look more familiar to the experienced Migrate user:

Basic vs. advanced UI permissions

With Migrate 2.6, we've introduced two levels of permission - migration information and advanced migration information. The advanced permission shows you everything you, as a migration developer, are used to seeing. But, sometimes, you may want to enable people who aren't migration developers to monitor and run migration processes. Now you can grant them a role with the migration information permission, and their view of the task listing page will look like:

They will have a more limited view when clicking the task name as well (in particular not having access to the feature in the next section!).

Editing of field mappings

The biggest leap forward in the Migrate UI with version 2.6 is the ability to edit a migration's field mappings and dependencies. In the past, these have always been defined in code, in the migration class constructor, but now the code-based configuration can be overridden through the UI:

You can select the source field from the available source fields which are not marked "DNM", set a default value for when no source field is mapped or the source value is empty, and select another migration for translating source IDs into Drupal IDs. You can also select source fields to mark "DNM":

and edit migration dependencies:

Invoking drush-based imports from the UI

As explained in the Migrate documentation, running migrations through drush is preferable to running them through the UI. However, what if you need to enable non-technical (or non-privileged-to-ssh-to-the-server-and-run-drush) users, i.e., the ones we've introduced the basic permission level for, to be able to perform imports, and your migrations are too large and/or slow to effectively run via Batch API? Well, WordPress Migrate has had an answer to that for a while - the ability to have the UI trigger a drush command running in the background on the server. This feature has now been generalized and brought into Migrate itself. When you visit the Migrate configuration page on a vanilla install, you'll see:

The first thing to do is to set the migrate_drush_path variable to point to your drush command:

$ which drush 
/Applications/acquia-drupal/drush/drush
$ drush vset migrate_drush_path /Applications/acquia-drupal/drush/drush
migrate_drush_path was set to "/Applications/acquia-drupal/drush/drush". 

You can also set it in your settings.php file:

$conf['migrate_drush_path'] = '/Applications/acquia-drupal/drush/drush'; 

If you're lucky, you'll be all set. If not, when you refresh the configuration page you'll see:

The configuration page attempts to run a drush status command, and if it fails notifies you. The most likely reason it would fail is if your web server PATH does not include PHP - fixing this is dependent on your environment, and left as an exercise for the reader. Once you do have it fixed, refreshing the configuration page should look like this:

You can choose whether the standard Import and Rollback operations always use Batch API, always use drush, or you can make both options available:

Finally, you can send an email notification to the account running the migration:

In my next post, I will talk about the new framework in Migrate 2.6 to ease the development of wizard-style UIs for defining and registering migrations.