fix: match relationship externalId values from nested records

- added nested dotted field fallback for org relationship records

- fixed Account__r.Name matching for csvfile to org upsert

- added unit test for nested target relationship records

Author: hknokh2

src/modules/models/job/MigrationJobTask.ts

@@ -1818,18 +1818,69 @@ export default class MigrationJobTask implements ISFdmuRunCustomAddonTask {
    * @returns Field value or undefined.
    */
   private _getRecordFieldValue(record: Record<string, unknown>, fieldName: string): string | undefined {
-    void this;
     if (!fieldName || !Object.prototype.hasOwnProperty.call(record, fieldName)) {
+      return this._getNestedRecordFieldValue(record, fieldName);
+    }
+    return this._normalizeRecordFieldValue(record[fieldName]);
+  }
+
+  /**
+   * Reads a nested record field value using a dotted relationship path.
+   *
+   * @param record - Record to inspect.
+   * @param fieldName - Dotted field path.
+   * @returns Field value or undefined.
+   */
+  private _getNestedRecordFieldValue(record: Record<string, unknown>, fieldName: string): string | undefined {
+    if (!fieldName.includes('.')) {
+      return undefined;
+    }
+
+    let currentValue: unknown = record;
+    const pathParts = fieldName
+      .split('.')
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0);
+    if (pathParts.length < 2) {
       return undefined;
     }
-    const rawValue = record[fieldName];
+
+    for (const pathPart of pathParts) {
+      if (!this._isRecordLike(currentValue) || !Object.prototype.hasOwnProperty.call(currentValue, pathPart)) {
+        return undefined;
+      }
+      currentValue = currentValue[pathPart];
+    }
+
+    return this._normalizeRecordFieldValue(currentValue);
+  }
+
+  /**
+   * Converts a raw record value to a non-empty string.
+   *
+   * @param rawValue - Raw value.
+   * @returns Normalized text value or undefined.
+   */
+  private _normalizeRecordFieldValue(rawValue: unknown): string | undefined {
+    void this;
     if (rawValue === null || typeof rawValue === 'undefined') {
       return undefined;
     }
     const textValue = String(rawValue);
     return textValue.length > 0 ? textValue : undefined;
   }
 
+  /**
+   * Determines whether a value can be traversed as a record object.
+   *
+   * @param value - Value to inspect.
+   * @returns True when the value is a plain record-like object.
+   */
+  private _isRecordLike(value: unknown): value is Record<string, unknown> {
+    void this;
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+  }
+
   /**
    * Reads the record Id value as a string.
    *

test/modules/job/migration-job-task.test.ts

@@ -72,6 +72,31 @@ const createTaskFixture = (): TaskFixtureType => {
 
 const createMap = (pairs: Array<[string, string]>): LookupIdMapType => new Map(pairs);
 
+describe('MigrationJobTask relationship external id matching', () => {
+  it('links target records by nested relationship external id values', () => {
+    const { task } = createTaskFixture();
+    task.scriptObject.externalId = 'Account__r.Name';
+
+    const sourceRecord: Record<string, unknown> = {
+      Id: 'a1B000000000001AAA',
+      'Account__r.Name': 'Acme Corp',
+    };
+    const targetRecord: Record<string, unknown> = {
+      Id: 'a1B000000000002AAA',
+      'Account__r': {
+        Name: 'Acme Corp',
+      },
+    };
+
+    task.registerRecords([sourceRecord], task.sourceData, false);
+    task.registerRecords([targetRecord], task.targetData, true);
+
+    assert.equal(task.sourceData.extIdToRecordIdMap.get('Acme Corp'), 'a1B000000000001AAA');
+    assert.equal(task.targetData.extIdToRecordIdMap.get('Acme Corp'), 'a1B000000000002AAA');
+    assert.equal(task.sourceToTargetRecordMap.get(sourceRecord), targetRecord);
+  });
+});
+
 describe('MigrationJobTask field capability warnings', () => {
   it('warns only for explicit update query fields that are not updateable', () => {
     const originalLogger = Common.logger;