Handling files in Drupal 7
NOTE: This applies to Migrate 2.4, for earlier versions of Migrate see http://drupal.org/node/1224042 and http://drupal.org/node/1349726. Also note that this requires Drupal 7.12 or later.
With Migrate 2.4, we completely redesigned the support for importing files into Drupal 7 file entities. This scheme makes the file destination and the file field handlers more consistent and more flexible, and coupled with improved handling of options and subfields, easier to implement. It is, however, incompatible with previous versions, so when upgrading you will need to change your migrations to use these techniques.
The redesigned support changes the syntax from mapping a field with a single entry such as $this->addFieldMapping('dest', 'src')->arguments($arguments); to using multiple entries. The first mapping you do will work like any standard field, taking the 'dest' and 'src' options, default values, etc. Meanwhile, the second and subsequent mappings will follow the form $this->addFieldMapping('dest:param')->defaultValue(); or $this->addFieldMapping('dest:param', 'src2');. While adding these fields it is helpful to review the source and destination fields in the Migrate UI to see what subfields await mapping.
File classes
Read more