[ISSUE] - Cross-object reference externalId (e.g. Account__r.Name) silently treats all records as inserts in csvfile->org direction (v5)

[parsam97]

Issue summary
When using a cross-object reference field as externalId (e.g. "Account__r.Name"), SFDMU v5 fails to match source CSV records against existing target org records during csvfile->org import. All records are silently classified as inserts - no error or warning is raised - even though the target org contains matching records and the Account__r.Name column is present in the CSV with correct values.

Additionally, the exported CSV contains no dedicated composite external ID column (the $$... column present in v4 exports). Only the constituent reference fields (e.g. Account__r.Name) appear as separate columns.

This worked correctly in v4.39.0 and below.

---

Steps to reproduce

export.json:

{
  "objectSets": [{
    "objects": [
      {
        "master": true,
        "externalId": "Name",
        "query": "SELECT Id, Name FROM Account WHERE Name IN ('Acme Corp')",
        "operation": "Readonly"
      },
      {
        "master": false,
        "externalId": "Account__r.Name",
        "query": "SELECT Id, Account__c FROM TestAccount__c",
        "operation": "Upsert"
      }
    ]
  }]
}

Step 1 - org->csv:
sf sfdmu run --sourceusername source@org.com --targetusername csvfile --path ./data/ --diagnostic --anonymise

Step 2 - csvfile->org:
sf sfdmu run --sourceusername csvfile --targetusername target@org.com --path ./data/ --diagnostic --anonymise --simulation

---

Expected behavior

Records matched by Account__r.Name and classified as updates:
[diagnostic] update classified: toInsert=0 toUpdate=N nonProcessed=0

---

Actual behavior
Setup, validation, and data retrieval complete without error. SFDMU correctly recognises and expands the external ID in the query. Despite matching records existing in the target org, all records are classified as inserts:
[diagnostic] update classified: toInsert=N toUpdate=0 nonProcessed=0

2026-03-26__08_02_12.log
2026-03-26__08_02_18.log

With --simulation removed, this would cause duplicate insert attempts against a live org with no warning.

Related issues

• [ISSUE] - Latest version of SFDMU(V5) is unable to read the referenced composite external Id keys defined in export.json #1166 - fixed __r externalId validation in v5; our validation passes correctly, but matching still fails
• [ISSUE] - Extraction returns #N/A for custom relationship traversal fields (e.g. Category__r.Code) even when org has data #1179 - reports #N/A in exported CSVs for __r fields; may share a common cause with this issue

---

Log file (required)

Two logs attached covering the full round-trip:

• 2026-03-26__08_02_12.log -- org -> csvfile
• 2026-03-26__08_02_18.log -- csvfile -> org

---

My best guess for root cause: When SFDMU v5 fetches target org records, jsforce returns relationship fields as nested objects ({ Account__r: { Name: "Acme Corp" } }). The v4 engine had a ___parseRecords step in sfdx.ts that flattened these to record["Account__r.Name"] = "Acme Corp" before matching. That step was removed in v5 (OrgDataService.ts). As a result, looking up record["Account__r.Name"] on any target org record returns undefined, every target record's external ID key is undefined, and no source record matches -> everything is an insert.

[92SGupta]

Hi @hknokh : I noticed as well that V5 contains no dedicated composite external ID column (the $$... column present in v4.39.0 exports). Is this done intentionally? With the current version (v5.6.3), as this field is missing, while resolving the dependencies and generating the source folder csv, it tries to add a new phantom record instead of identifying the existing record. When I tried to add the externalID field in the retrieved csvfile locally, it started to work fine and resolve the dependencies as per V4.39.0.

[hknokh]

Hello,

Thank you for reporting this issue.
I reproduced this issue and fixed it in the latest version of the SFDMU.
Please reinstall the plugin and try again.

Root cause:

• Target org records returned by the Salesforce API keep relationship fields as nested objects, for example Account__r: { Name: "..." }. The v5 matching code read only flat keys like Account__r.Name, so the target external ID value was empty and existing rows were treated as inserts.

Fix details:

• SFDMU now resolves dotted relationship paths from both flat CSV columns and nested Salesforce API relationship objects.
• I added coverage for ScriptObject.externalId values such as Account__r.Name.
• I verified csvfile to org upsert with Account__r.Name. Before the fix it planned toInsert=1 toUpdate=0. After the fix it plans and executes toInsert=0 toUpdate=1.

Please, see also the doc articles:

• externalId
• Composite External ID keys

Best regards

[parsam97]

Hi,

Thanks very much for the fix. I will test the newest version.

Quick question: our workflow is always csvfile to org. I would like to write some tests now to assert SFDMU works as expected, whenever I want to upgrade to latest release. Would you say parsing the log file is really the only way to assert if a run command produces the expected inserts and updates? There doesn't seem to be any other source to check for this information and make the assertion.

Thank you