BTMash

Last week, I posted about performing a content/user migration from Drupal 6 to Drupal 7 using the migrate module (instead of going via the upgrade route or the 'use the interns at work and make them undergo hell for a few days' of copy content and users one-by-one for migration).

UPDATE - March 13, 2012: Added in findings by Andre and my thoughts.

I posted how to get the migrate module to know that there is a new migration that can be performed and now, we will define how to perform a basic mapping of users with roles from Drupal 6 to Drupal 7 ( as a note, this is a mapping that could be performed against any database or files; the migrate module comes with an example of how to do mappings with files). As a note, the entire code example in full can be found at the bottom of the page (or click here)

We first define our migration class:

class RedcatUserMigration extends Migration {
 ...
}

The above will let migrate know that there is a new Migration class (called MyUserMigration) from which content will require migration. It is now time to define what goes inside the class. For this, we must define the class constructor:

  public function __construct() {
    parent::__construct();
    $this->description = t('Migrate legacy users');
  }

We define the source fields (these would be the primary keys and any fields that may not be found in the initial mapping query. More on that at the bottom:

    $source_fields = array(
      'uid' => t('User ID'),
      'roles' => t('The set of roles assigned to a user.'),
    );

We need to define where to get the data from and set the Source and Destination values. In my scenario, I am dealing with a mysql database that is on the same server as my destination database so I directly refer to that database. In other circumstances, you should follow part of the documentation here and here.

    $query = db_select(MY_MIGRATION_DATABASE_NAME .'.users', 'u')
      ->fields('u', array('uid', 'name', 'pass', 'mail', 'created', 'access', 'login', 'status', 'init'))
      ->condition('u.uid', 1, '>');
    $this->source = new MigrateSourceSQL($query, $source_fields);
    $this->destination = new MigrateDestinationUser();

About the query that gets defined above: please note that all the fields that are defined in there are automatically included as fields that can be mapped to a destination field (so we have defined that there are source mappings for: uid, name, pass, mail, created, access, login, status, and init). You can add any additional conditions that must pass to import a limited set of users (I only want to import users with a uid > 1; yours might have conditions on emails or users).

Also note that if your passwords were previously in md5 format, you can have them imported and automatically converted by having the following as your destination:

    $this->destination = new MigrateDestinationUser(array('md5_passwords' => TRUE));

We now need to create a mapping to track the relationship between the source rows from the source database and their resulting Drupal objects; we pass along the schema definitions for the primary key of our source and destination databases (we have to be specific for our source).

    $this->map = new MigrateSQLMap($this->machineName,
      array(
        'uid' => array(
          'type' => 'int',
          'unsigned' => TRUE,
          'not null' => TRUE,
          'description' => 'D6 Unique User ID',
          'alias' => 'u',
        )
      ),
      MigrateDestinationUser::getKeySchema()
    );

From the above, we have now defined for the RedcatUserMigration to run the constructor of the parent class and provide a descriptive name and mapping for the Migration so that when we go from admin->content->migrate, we will now see:

With that out of the way, we are finally ready to move on to the actual mapping. The syntax of this consists of defining the destination field you wish to map against the source field($this->addFieldMapping('destination', 'source')). You can define mappings whereby to check that there are no duplicates (in case you have usernames or emails in your new database that were also in your previous site - an example could be the admin account)($this->addFieldMapping('uniques', 'duplicates')->dedupe('table_name', 'uniques');).
You can even provide default values for fields that don't necessarily require a mapping ($this->addFieldMapping('signature_format')->defaultValue('filtered_html');) or say the value of a field does not matter and you are not going to be migrating anything related to that field ($this->addFieldMapping('path')->issueGroup(t('DNM')); - DNM means Do Not Migrate).

So our primary mapping looks like:

    $this->addFieldMapping('name', 'name')->dedupe('users', 'name');
    $this->addFieldMapping('pass', 'pass');
    $this->addFieldMapping('mail', 'mail')->dedupe('users', 'mail');
    $this->addFieldMapping('language')->defaultValue('');
    $this->addFieldMapping('theme')->defaultValue('');
    $this->addFieldMapping('signature')->defaultValue('');
    $this->addFieldMapping('signature_format')->defaultValue('filtered_html');
    $this->addFieldMapping('created', 'created');
    $this->addFieldMapping('access', 'access');
    $this->addFieldMapping('login', 'login');
    $this->addFieldMapping('status', 'status');
    $this->addFieldMapping('picture')->defaultValue(0);
    $this->addFieldMapping('init', 'init');
    $this->addFieldMapping('timezone')->defaultValue(NULL);
    $this->addFieldMapping('path')->issueGroup(t('DNM'));
    $this->addFieldMapping('pathauto_perform_alias')->defaultValue('1');
    $this->addFieldMapping('roles', 'roles');

So far, we have defined a ton of mappings and for the most part, we are through with this.

On a side note, in my code, I did not do a mapping of the user id from the old site to the new one. If you wanted to do that as well, then you would have the following in your mappings:

    $this->addFieldMapping('is_new')->defaultValue(TRUE);
    $this->addFieldMapping('uid', 'uid');

This will create new users in your system with their old user ids. The biggest gain from this would be that doing a mapping from the old system to the new one is much easier (you don't have to do any additional querying to figure out how the old user id maps out to the new one when migrating other content). However, the downside will be that if you are introducing new users in your system prior to this migration and the usernames from old uid and new uid don't match up, that user with the uid conflict with not migrate over into your site. In my scenario, it was easy enough to let the user ids roll forward (its actually not difficult to have a userid dependency from another migration) so I have not bothers with retaining the old user id. Nonetheless, something to think about.

However, we have not covered a mapping for when we have data that covers multiple roles. In the scenario we have above, that data would be roles. And the migrate module will warn that such a mapping has not been created (in the above scenario, your users will migrate; they just won't have any roles attached to them). So the way to do this is by preparing a row and massaging in any new data (or existing data if we want to clean it up or replace it). This is just by implementing prepareRow()

  public function prepareRow($current_row) {
    $source_id = $current_row->uid;
    $query = db_select(MY_MIGRATION_DATABASE_NAME .'.users_roles', 'r')
      ->fields('r', array('uid', 'rid'))
      ->condition('r.uid', $source_id, '=');
    $results = $query->execute();
    $roles = array('2' => '2');
    foreach ($results as $row) {
      $roles[$row->rid] = $row->rid;
    }
    $current_row->roles = $roles;
    return TRUE;
    // return FALSE if you wish to skip a particular row
  }

There is a lot happening above so let me explain the short of it. In my scenario, I had created my roles and their role IDs happened to match the role IDs I had in my old site. So I perform a query to get the roles a particular user has (defined by $current_row which has all of the mappings defined from above so we use the uid). We then create a roles variable to which we attach all the role IDs that it can find. And that's all!

Once all of this is set up, we are ready to run drush migrate-import RedcatUser and all your users will now be imported along with their correct roles into the new website!

As a final code mashup, all of the code from above looks like the following:

class RedcatUserMigration extends Migration {
  public function __construct() {
    parent::__construct();
    $this->description = t('Migrate REDCAT users');
 
    $source_fields = array(
      'uid' => t('User ID'),
      'roles' => t('The set of roles assigned to a user.'),
    );
 
    $query = db_select(REDCAT_MIGRATION_DATABASE_NAME .'.users', 'u')
      ->fields('u', array('uid', 'name', 'pass', 'mail', 'created', 'access', 'login', 'status', 'init'))
      ->condition('u.name', array('admin', 'rgates'), 'NOT IN')
      ->condition('u.uid', 0, '>');
    $this->source = new MigrateSourceSQL($query, $source_fields);
    $this->destination = new MigrateDestinationUser();
 
    $this->map = new MigrateSQLMap($this->machineName,
      array(
        'uid' => array(
          'type' => 'int',
          'unsigned' => TRUE,
          'not null' => TRUE,
          'description' => 'D6 Unique User ID',
          'alias' => 'u',
        )
      ),
      MigrateDestinationUser::getKeySchema()
    );
 
    // Make the mappings
    $this->addFieldMapping('name', 'name')->dedupe('users', 'name');
    $this->addFieldMapping('pass', 'pass');
    $this->addFieldMapping('mail', 'mail')->dedupe('users', 'mail');
    $this->addFieldMapping('language')->defaultValue('');
    $this->addFieldMapping('theme')->defaultValue('');
    $this->addFieldMapping('signature')->defaultValue('');
    $this->addFieldMapping('signature_format')->defaultValue('filtered_html');
    $this->addFieldMapping('created', 'created');
    $this->addFieldMapping('access', 'access');
    $this->addFieldMapping('login', 'login');
    $this->addFieldMapping('status', 'status');
    $this->addFieldMapping('picture')->defaultValue(0);
    $this->addFieldMapping('init', 'init');
    $this->addFieldMapping('timezone')->defaultValue(NULL);
    $this->addFieldMapping('path')->issueGroup(t('DNM'));
    $this->addFieldMapping('pathauto_perform_alias')->defaultValue('1');
    $this->addFieldMapping('roles', 'roles');
  }
 
  public function prepareRow($current_row) {
    $source_id = $current_row->uid;
    $query = db_select(REDCAT_MIGRATION_DATABASE_NAME .'.users_roles', 'r')
      ->fields('r', array('uid', 'rid'))
      ->condition('r.uid', $source_id, '=');
    $results = $query->execute();
    $roles = array('2' => '2');
    foreach ($results as $row) {
      $roles[$row->rid] = $row->rid;
    }
    $current_row->roles = $roles;
    return TRUE;
    // return FALSE if you wish to skip a particular row
  }
}

I hope all of this is helpful. If something doesn't make a lot of sense, leave a comment! I'll try and improve this documentation. And next time, I'll post how to migrate a basic page with taxonomy terms and attached files.