Data is not saved on the entity when the source and destination field names are the same but have different types

I'm migrating from Drupal 7 to Drupal 9.

On the source Drupal 7 user entity there is a Text (list) field with various values. These need to be migrated to a taxonomy_term reference field on the Drupal 9 site, where the referenced terms have names corresponding to the values provided in the D7 source.

I'm using entity_lookup to link the Text (list) values to entities on the D9 site, and this works fine, but only if the source D7 and destination D9 field names are different.

So, on the Drupal 7 site and the Drupal 9 site when both fields have the same name. Let's say the name is field_organisations. I'm using the following in my process plugin:

process:
  field_organisations:
    -
      plugin: sub_process
      source: field_organisations
      process:
        target_id:
          plugin: entity_lookup
          entity_type: taxonomy_term
          bundle_key: vid
          bundle: organisations
          value_key: name
          source: value

Regardless of what I do, after migration, none of the field_organisations data have been migrated.

However, if I change the name of the destination field so that it does not match the source field, like this:

process:
  field_organisations_new:
    -
      plugin: sub_process
      source: field_organisations
      process:
        target_id:
          plugin: entity_lookup
          entity_type: taxonomy_term
          bundle_key: vid
          bundle: organisations
          value_key: name
          source: value

... then it works fine - even though the only difference is that the field name has been changed.

It's as if Drupal is erroneously trying to overwrite the D9 term reference field with the D7 list (text) data because the field names are the same, and ignoring my explicit process configuration.

But I've seen no documentation to say this is expected and don't know how to stop it from happening.

I have been given the solution for this via the Drupal Slack channel (thankyou, https://www.drupal.org/u/mikelutz and https://www.drupal.org/u/osab).

The problem was that my migration was using the wrong class.

My migration .yml file contained:

class: Drupal\user\Plugin\migrate\User

Changing this to:

class: Drupal\migrate\Plugin\Migration

Fixed the problem.

Explanation

The core d7_user migration uses Drupal\user\Plugin\migrate\User specifically to populate the user fields dynamically from a D7 source.

When writing a custom migration, we need to use the standard Drupal\migrate\Plugin\Migration class as we are defining the process and don’t need or want to have it overwritten.

Migration .ymls are plugin definitions. Plugin definitions take a class key to determine which plugin class to pass the configuration to.

For custom migrations, that should almost always be \Drupal\migrate\Plugin\Migration unless we are providing our own class for custom advanced handling.

Some core migrations do use other classes for the migration plugin, usually to dynamically add processes, as they were all written for the core upgrade UI, which needs to dynamically insert processes for detected D7 fields.

It is important if we are writing custom migration plugin definitions to use the correct plugin class for our use case.

\Drupal\migrate\Plugin\Migration is the base class, that basically says run the processes as defined in the .yml with no modification.