Relation Migrate integration and *reference upgrade path

There was my patch committed to Relation module (which is great - if you have not tried it yet definitely do) today, that adds Migrate support to Relation and uses it to provide upgrade path from Term/User/Node/Entity reference fields to Relation. I hope that this feature will be useful to a lot of people. In order to use new functionality you'd need to enable Relation migrate, which comes together with Relation.

Migrate integration

Module implements class MigrateDestinationRelation, which is a destination plugin for Migrate. You can use this class in your custom migrate scripts in a very similar way as you'd use MigrateDestinationNode, which is most likely used when migrating nodes. The only difference will be in mapping, which should be done in prepare() or prepareRow(). This is required because of the complexity of relation_endpoint field, which requires a lot of information in order to properly build a relation. Here is an example of typical mapping definition:

public function prepare(stdClass $relation, stdClass $source_row) {
  $relation->endpoints[LANGUAGE_NONE] = array(
    array('entity_type' => $source_row->source_type, 'entity_id' => $source_row->source_id),
    array('entity_type' => $source_row->destination_type, 'entity_id' => $source_row->destination_id),
  );
}

This example is taken from actual implementation of *reference upgrade path in Relation migrate.

Term/User/Node/Entity reference upgrade path

A typical request by people thinking about using Relation on their existing sites is upgrade path from *reference modules. Migrate integration now allows us to do this. You shouldn't spend more than a few clicks to have this done. I will demonstrate this feature on a standard Drupal 7 installation. I have generated 50 nodes that are tagged with taxonomy terms. This is done via field_tags field, which is obviously a Taxonomy reference. I will first create new Relation type and configure it to allow relations from nodes to terms.

Now I have to configure Relation migrate. In order to do that I have to navigate to configuration page (found under Structure -> Relation types -> Migration). You'll find configuration for every type of reference field here. Currently we support Term (core), Node (References), User (References) and Entity reference. As I already mentioned I use standard installation for this demo, but other supported fields should appear here if there are any. Now I just have to enable upgrade path for field_tags and select relation type that should be used for this upgrade.

If I navigate to Content -> Migrate (Migrate UI must be enabled) i find four migration classes, each for every supported reference field type. I can see that I have some unmigrated term references, which are obviously tags on my nodes. I select this class and start the migiration process.

When migrate script completes it's job I end up with a lot of new relation, which are tags on my nodes.

Described functionality is currently available in 7.x-1.x-dev release of Relation module. It is relatively new and as such not very well tested. Please report back in the issue queue if you find any bugs or encounter any problems. I'd be glad to help. Hope you will enjoy Relation module and it's Migrate integration.