Company card - Unique ID not premapped when import the same file company card CSV

[applause-bot]

If you haven’t already, check out our contributing guidelines for onboarding. To join our Slack channel, fill out this form.

---

Version Number: v9.4.84-0
Reproducible in staging?: Yes
Reproducible in production?: Yes
If this was caught during regression testing, add the test name, ID and link from BrowserStack: https://test-management.browserstack.com/projects/2219752/test-runs/74548874/folder/13176706/108116228/1771051495?sort=-identifier
Email or phone of affected tester (no customers): lekima20+611809@gmail.com
Issue reported by: Applause Internal Team
Bug source: Regression TC Execution
Device used: Win 11/Chrome
App Component: Workspace Settings

Action Performed:

Precondition: Create a workspace currency USD

1. Open https://staging.new.expensify.com
2. Admin go to the Company card tab in Workspace setting
3. Click Add cards > Next
4. Choose the "Import transactions from file" > Next
5. Import CSV file
6. Scroll down to "Unique ID" column > change "Ignore" to "Unique ID" > Import > Got it
7. After the card list appear, click on Settings
8. Click Import spreadsheet
9. Upload the same file again
10. Scroll down to observe "Unique ID" column

Expected Result:

When upload the same file again, "Unique ID" column should be premapped to "Unique ID"

Actual Result:

When upload the same file again, "Unique ID" column displays "Ignore"

Workaround:

Unknown

Platforms:

• Android: App
• Android: mWeb Chrome
• iOS: App
• iOS: mWeb Safari
• iOS: mWeb Chrome
• Windows: Chrome
• MacOS: Chrome Safari

Screenshots/Videos

Bug7262887_1789700485300.Recording__2493.mp4

Bug7262887_1789702672142!CSV_card_file.csv

View all open jobs on GitHub

Applause Internal Information
Exported by: Julia Ponikarchuk
Bug ID: 7262887

Issue Owner

Current Issue Owner: @hoangzinh

[applause-bot]

While Applause doesn't embed attachments for this bug, here are the links for quick view:
https://platform.applause.com/services/links/v1/external/6de50b4cf19e0db8735c81832282496408008cbcbff180ef1e9615f5e0946de7

https://platform.applause.com/services/links/v1/external/bc0dd3d164133a023530beeabf50aa33886ce36c7159a13b7f11516db2360360

[MelvinBot]

Proposal

What is the root cause of that problem?

Two gaps in src/libs/importSpreadsheetUtils.ts mean the Unique ID column can never be pre-mapped:

1. The saved mapping for Unique ID is deliberately thrown away. getCompanyCardColumnMappings() restores every saved role positionally except externalID, which it skips at importSpreadsheetUtils.ts:273-280. That is why only Unique ID falls back to "Ignore" on the second upload while Merchant, Amount, Currency and the rest come back correctly.

2. Header auto-detection can't claim it either. The guard's comment says "a header that names the column outright is unambiguous, so the detection pass above can still claim it" — but findColumnName() has no uniqueid/externalid case anywhere in its switch (importSpreadsheetUtils.ts:11-225). CSV_IMPORT_COLUMNS.EXTERNAL_ID appears exactly once in that whole file — in the guard itself. So the fallback the guard relies on does not exist.

The guard came from Add mappable Unique ID field to company card CSV import (merged 2026-08-28) and was moved into its current location by [Payment due abdulrahuman5196] Improve column auto-mapping when the file structure is different (merged 2026-09-17), which is also where the now-inaccurate comment was added.

What changes do you think we should make in order to solve the problem?

Teach findColumnName() the Unique ID header — add a case to the switch in importSpreadsheetUtils.ts mapping uniqueid / unique_id / externalid to CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID. This is safe for other import flows because the availability check at importSpreadsheetUtils.ts:206-222 discards roles that aren't offered, and company cards is the only flow offering EXTERNAL_ID.

This alone fixes the reported case, and it also fixes the first import: App's own downloadable template ships a Unique ID header (ImportFromFileStep.tsx:41) that is currently never detected. The same missing-header-case gap also leaves Sales Date, Original Amount and Original Currency unmapped on a first import, so those aliases are worth adding in the same change.

Keep the externalID positional guard as-is. It is still doing real work: when the user maps no Unique ID, the backend stores a synthetic index one past the last real column (CompanyCards.ts:109-119), and restoring that onto a wider file would point Unique ID at an unrelated column, whose repeated values would make the backend dedupe valid transactions away. Its comment should be corrected to stop claiming a detection fallback that didn't exist.

Two test updates are needed: tests/unit/ImportSpreadsheetTest.ts:183-195 currently asserts the buggy outcome for a Unique ID-headed column, and tests/unit/CompanyCardsCSVImportTest.ts has no header-detection case for Unique ID.

What alternative solutions did you explore? (Optional)

Persist whether externalID was user-mapped or synthetic (for example a hasMappedExternalID flag in uploadLayoutSettings) so the positional restore can be trusted. That fixes headerless files too, but it needs a backend change to uploadLayoutSettings, so it is a bigger follow-up rather than the fix for this issue.

Investigation details and evidence

Why only Unique ID regresses. On re-upload, CompanyCardsImportedPage reads the saved layout from uploadLayoutSettings.columnMappings (CompanyCardsImportedPage.tsx:87) and hands it to getCompanyCardColumnMappings, which runs header detection first and then a positional fallback from the saved layout. Every role except externalID survives that fallback, which is exactly the reported asymmetry.

externalID is saved. It is pushed unconditionally into the outgoing mappings at CompanyCards.ts:109-119 and sent with ImportCSVCompanyCards. App never writes uploadLayoutSettings optimistically; it is persisted server-side and read back, so on step 9 the saved mapping does contain a valid externalID index for the same file — the client just discards it.

Alternative explanations ruled out. Not an Onyx staleness problem: the re-map effect re-runs whenever spreadsheet.data or savedColumnMappings changes and waits for feed metadata to load (CompanyCardsImportedPage.tsx:92-120). Not a duplicate-role collision either: the usedRoles bookkeeping only skips a role that another column already claimed, and no column can claim externalID in the first place. Not a backend persistence gap: the other roles from the same saved object restore fine.

Platform-independent. The logic is shared, which matches the report reproducing on Android, iOS and Chrome.

Related issues. No duplicate found. Date column on XLSX personal card import generates random numbers and can't be added touches spreadsheet column handling but is a different flow and a different mechanism.

Confidence: high. Code evidence is conclusive and there is an existing unit test that explicitly asserts the current (buggy) behaviour.

---

Next Steps for Contributor+ team:
To accept: @MelvinBot implement [this](https://github.com/Expensify/App/issues/101511) to create a draft PR.
To refine: @MelvinBot <your feedback>
To reject: Explain why you are rejecting Melvin's proposal.

---

view run

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @hoangzinh (External)

[melvin-bot]

Unable to auto-create job on Upwork. The BZ team member should create it manually for this issue.

[g9kg74d5tc-lgtm]

Proposal

What is the root cause of that problem?

The saved externalID mapping is intentionally not restored positionally in getCompanyCardColumnMappings(), because the company-card importer can append a synthetic external-ID column when the user does not map one. Reusing that saved index on another file could point Unique ID at an unrelated column and cause incorrect backend deduplication.

That safeguard is correct and should stay.

The actual gap is earlier in the same function: the header-first detection pass calls findColumnName(header, rolesForDetection), but findColumnName() has no mapping for Unique ID / External ID. The downloadable company-card template itself contains a Unique ID header, which normalizes to uniqueid, yet that value currently falls through the switch and returns an empty role.

As a result:

1. On first import, a real Unique ID header is not auto-mapped.
2. On re-import, the positional saved externalID mapping is correctly skipped for safety.
3. Because header detection also fails, the column ends up as Ignore.

That explains why the other columns are restored/detected while Unique ID is not.

What changes do you think we should make in order to solve the problem?

Keep the existing externalID positional guard unchanged and fix only the missing semantic header detection.

In src/libs/importSpreadsheetUtils.ts, add explicit aliases in findColumnName():

case 'uniqueid':
case 'unique_id':
case 'externalid':
case 'external_id':
    attribute = CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID;
    break;

Because the existing columnRoles availability check runs after detection, this remains safe for every other spreadsheet-import flow: EXTERNAL_ID is only returned when that role is actually selectable in the current context.

I would keep this PR scoped to Unique ID rather than bundling unrelated header aliases. That gives us the smallest regression surface and directly fixes the reported case.

Regression coverage

I would add focused tests for both sides of the contract:

1. In tests/unit/CompanyCardsCSVImportTest.ts:

   • Unique ID maps to EXTERNAL_ID.
   • External ID maps to EXTERNAL_ID.
   • The mapping only occurs when EXTERNAL_ID is an available role.

2. In tests/unit/ImportSpreadsheetTest.ts:

   • Keep the existing test proving a saved externalID index is not restored positionally when there is no unambiguous header.
   • Add a re-import case where the same column has a Unique ID header and savedColumnMappings.externalID exists: header detection must claim the real column even though positional restoration remains disabled.

That second test is important because it protects the exact intended distinction: unsafe saved index = ignored; explicit current-file header = trusted.

What alternative solutions did you explore? (Optional)

• Restore the saved externalID index directly. Rejected because it removes the safety added for synthetic IDs and can map an unrelated column on a structurally different file, causing bad deduplication.
• Persist extra metadata saying whether the saved externalID was user-mapped or synthetic. This would also work, including for headerless files, but it requires a broader persistence/backend contract change and is unnecessary for the reported CSV/template flow.
• Special-case Unique ID inside getCompanyCardColumnMappings(). Rejected because findColumnName() is already the canonical header-to-role layer; fixing the missing alias there keeps the mapping logic centralized and reusable.

I have not opened a PR yet. I would implement only after the job/proposal is approved, per the contributing flow.

[melvin-bot]

📣 @g9kg74d5tc-lgtm! 📣
Hey, it seems we don’t have your contributor details yet! You'll only have to do this once, and this is how we'll hire you on Upwork.
Please follow these steps:

1. Make sure you've read and understood the contributing guidelines.
2. Get the email address used to login to your Expensify account. If you don't already have an Expensify account, create one here. If you have multiple accounts (e.g. one for testing), please use your main account email.
3. Get the link to your Upwork profile. It's necessary because we only pay via Upwork. You can access it by logging in, and then clicking on your name. It'll look like this. If you don't already have an account, sign up for one here.
4. Copy the format below and paste it in a comment on this issue. Replace the placeholder text with your actual details.
   
   Format:

Contributor details
Your Expensify account email: <REPLACE EMAIL HERE>
Upwork Profile Link: <REPLACE LINK HERE>

[melvin-bot]

@hoangzinh Whoops! This issue is 2 days overdue. Let's get this updated quick!

[melvin-bot]

@hoangzinh Eep! 4 days overdue now. Issues have feelings too...