Problem/Motivation
The docs say:
/**
* Import the row.
*
* Derived classes must implement import(), to construct one new object
* (pre-populated) using ID mappings in the Migration.
*
* @param \Drupal\migrate\Row $row
* The row object.
* @param array $old_destination_id_values
* (optional) The old destination IDs. Defaults to an empty array.
*
* @return array|bool
* An indexed array of destination IDs in the same order as defined in the
* plugin's getIds() method if the plugin wants to save the IDs to the ID
* map, TRUE to indicate success without saving IDs to the ID map, or
* FALSE to indicate a failure.
*/
public function import(Row $row, array $old_destination_id_values = []);
I am unclear what $old_destination_id_values represents. Old in what way? In which circumstances is this the default empty array?
Looking at the calling code, it *looks* like this is the values from the migrate map for the destination entity if this source has previously been migrated already.
In other words, the parameter is empty the first time you migrate a source row, and has the map's destination ID values on a subsequent update.
The documentation should explain this.