Last updated 4 September 2017. Created on 20 July 2011.
Edited by jpoesen, msti, heddn, mikeryan. Log in to edit this page.

Some field types are more complex than others - in particular, they support a number of options controlling their behavior, or subfields providing additional data. These options or subfields can be mapped like regular fields - for example, to map the summary subfield of a text field:

$this->addFieldMapping('field_text', 'main_text');
$this->addFieldMapping('field_text:summary', 'teaser_text');

You can view all of the available subfields either in the migrate UI under the destination's tab for a specific migration or by using the drush migrate-fields-destination command. Just like regular field mappings if you leave a subfield un-mapped it will assume the Drupal default value for that column which varies depending on the type of field in question.

One common example is the 'language' subfield - this indicates the value of the field when requested for a given language and many fields have this additional data. The default is LANGUAGE_NONE ('und') - the default value when a specific language is not requested. If you were importing translated data you may want to set the appropriate language code with something like the following:


Text fields

Text fields (fields with machine names of 'text', 'text_long', or 'text_with_summary') have the following subfields:

  • summary: A short version of the contents of the field (i.e., a "teaser" or "excerpt").
  • format: The Drupal text format to apply when displaying the field (e.g., "filtered_html").

Term reference fields

Term references on Drupal 7 (fields of the type 'taxonomy_term_reference') have the following options:

  • source_type: If the option value is 'tid', then the incoming value is assumed to be a valid term ID in the destination Drupal instance. Otherwise, it is assumed to be a term name (the default behavior). Note that you'll want to set this to 'tid' if the mapping has a source migration (the sourceMigration() method is used on the mapping).
  • create_term: If this option is TRUE (or any value not FALSE/0/etc.) and source_type is not 'tid', then if the name passed as the value here does not already exist in the destination vocabulary, it will be created. The default behavior is to not create a term.
  • ignore_case: If this option is TRUE, then case differences (uppercase vs. lowercase) between source data and existing term names will be ignored. The default behavior is to not ignore case.
$this->addFieldMapping('field_taxonomy_reference', 'legacytermid')
$this->addFieldMapping('field_tags', 'termname');

Migrate UI wizard

In the Migrate UI wizard, terms will not be mapped automatically. Via #2063203: Automatically map term references using the UI:

  • Go to the field mapping editor for your node content type migration.
  • For any term reference fields, set the source field to the appropriate vocabulary on your source system, and set the source migration to the migration of that vocabulary.
  • Right under the term reference field, there will be a ':source_type' subfield - set the default value in that row to "tid".

shot_20162107-123014.png60.84 KB

Looking for support? Visit the forums, or join #drupal-support in IRC.


jmonkfish’s picture

For the advanced topics, nothing is presented for how to handle complex fields with multiple values. How can I pass in both the source_path and the description for a File field with multiple values?
I left some feedback also on #1279778: Improve argument passing to fields

Updated: mikeryan directed me to migrate_example WineWineMigration for an example on how to do this (#1509750: Trying to map subfields (file field description) to a multi-value file field), and I added that example to this page.

Peter Törnstrand’s picture

I struggled to map a simple taxonomy term using the source_type option. I finally found out how to do it:


Also, this must be defined after you have mapped the field it self.

$this->addFieldMapping('field_publication_type', 'PublicationType')
      ->callbacks(array($this, 'convertPublicationType'));

Peter Törnstrand, Happiness

adrupaler’s picture

is this code works for mapping entity reference? Can anyone give me an example for entity reference field mapping?

$this->addFieldMapping('field_author', 'field_author')->sourceMigration('Creator');

alexweber’s picture

That should work but you might need Migrate Extras for the field handler

t_en’s picture

If you wish to migrate start and end date/time to a date field. It took me some time to figure out how to set it up:

$this->addFieldMapping('field_date', 'start_date');
$this->addFieldMapping('field_date:to', 'end_date');

The date module's (version 7.x-2.7) migrate integration can handle the following subfields: "timezone", "rrule", and "to".

hani.atalla’s picture

We are migrating content to Open Atrium 2 and that entails creating OA spaces, space membership, etc. The migration for these is working, however under each space we need to create a section (document, calendar, discussion, file, etc.) The section type is an OA taxonomy term (machine name "section_type") that defines these.

When we create a section we know what type it should be: e.g. "4" is a document section so it is a defaultValue and the section type term reference field in the section content type is "field_oa_section" . In migrating/creating sections I am doing:


but that isn't working and it is not assigning a "document section type" to the newly created section". Any help is much appreciated.


ultrabob’s picture

Peter Törnstrand claimed in his comment, that the source_type needed to be declared AFTER the field value. I don't know whether that is true or not, but it might be something to look at.

cesar ll’s picture

Please help

function image_name($propertyid){

  $queryimage = Database::getConnection('MI_DB', 'temporal')
      ->select('images', 'im')
      ->fields('im', array(
      ->condition("type", 'Widescreen', "=")
      ->condition("propertyrecid", $propertyid, "=");
      $result = $queryimage->execute()->fetchAll();

      return $result[0]->filename;


How can I value a field from the source table and store it in a variable ($agentid= 'agent_ID'):

$this->addFieldMapping('idexample', 'agent_ID');


Thank you