Add mappable Unique ID field to company card CSV import

src/languages/de.ts

@@ -6042,6 +6042,7 @@ _Für ausführlichere Anweisungen [besuchen Sie unsere Hilfeseite](${CONST.NETSU
                     comment: 'Beschreibung',
                     category: 'Kategorie',
                     tag: 'Tag',
+                    uniqueID: 'Eindeutige ID',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Bitte weisen Sie jeder der folgenden Eigenschaften eine Spalte zu: ${missingColumns}.`,

src/languages/el.ts

@@ -6154,6 +6154,7 @@ _Για πιο αναλυτικές οδηγίες, [επισκεφθείτε τ
                     category: 'Κατηγορία',
                     tag: 'Ετικέτα',
                     cardName: 'Όνομα κάρτας',
+                    uniqueID: 'Μοναδικό αναγνωριστικό',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Παρακαλούμε αντιστοιχίστε μια στήλη σε καθεμία από τις ιδιότητες: ${missingColumns}.`,

src/languages/en.ts

@@ -6127,6 +6127,7 @@ const translations = {
                     comment: 'Description',
                     category: 'Category',
                     tag: 'Tag',
+                    uniqueID: 'Unique ID',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Please assign a column to each of the attributes: ${missingColumns}.`,

src/languages/es.ts

@@ -5916,6 +5916,7 @@ ${amount} para ${merchant} - ${date}`,
                     comment: 'Descripción',
                     category: 'Categoría',
                     tag: 'Etiqueta',
+                    uniqueID: 'ID única',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Por favor, asigna una columna a cada uno de los atributos: ${missingColumns}.`,

src/languages/fr.ts

@@ -6050,6 +6050,7 @@ _Pour des instructions plus détaillées, [visitez notre site d’aide](${CONST.
                     comment: 'Description',
                     category: 'Catégorie',
                     tag: 'Étiquette',
+                    uniqueID: 'ID unique',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Veuillez attribuer une colonne à chacun des attributs : ${missingColumns}.`,

src/languages/it.ts

@@ -6007,6 +6007,7 @@ _Per istruzioni più dettagliate, [visita il nostro sito di assistenza](${CONST.
                     comment: 'Descrizione',
                     category: 'Categoria',
                     tag: 'Tag',
+                    uniqueID: 'ID univoco',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Assegna una colonna a ciascuno degli attributi: ${missingColumns}.`,

src/languages/ja.ts

@@ -5935,6 +5935,7 @@ _詳しい手順については、[ヘルプサイトをご覧ください](${CO
                     comment: '説明',
                     category: 'カテゴリ',
                     tag: 'タグ',
+                    uniqueID: '一意の ID',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `各属性に列を割り当ててください：${missingColumns}`,

src/languages/nl.ts

@@ -5998,6 +5998,7 @@ _Voor meer gedetailleerde instructies, [bezoek onze help-site](${CONST.NETSUITE_
                     comment: 'Omschrijving',
                     category: 'Categorie',
                     tag: 'Label',
+                    uniqueID: 'Unieke ID',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Wijs een kolom toe aan elk van de attributen: ${missingColumns}.`,

src/languages/pl.ts

@@ -6023,6 +6023,7 @@ _Aby uzyskać bardziej szczegółowe instrukcje, [odwiedź naszą stronę pomocy
                     comment: 'Opis',
                     category: 'Kategoria',
                     tag: 'Tag',
+                    uniqueID: 'Unikalny identyfikator',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Przypisz kolumnę do każdego z atrybutów: ${missingColumns}.`,

src/languages/pt-BR.ts

@@ -5998,6 +5998,7 @@ _Para instruções mais detalhadas, [visite nossa central de ajuda](${CONST.NETS
                     comment: 'Descrição',
                     category: 'Categoria',
                     tag: 'Etiqueta',
+                    uniqueID: 'ID exclusivo',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `Atribua uma coluna a cada um dos atributos: ${missingColumns}.`,

src/languages/zh-hans.ts

@@ -5795,6 +5795,7 @@ _如需更详细的说明，请[访问我们的帮助网站](${CONST.NETSUITE_IM
                     comment: '描述',
                     category: '类别',
                     tag: '标签',
+                    uniqueID: '唯一 ID',
                 },
                 csvErrors: {
                     requiredColumns: (missingColumns: string) => `请为以下每个属性分配一列：${missingColumns}`,

src/libs/actions/CompanyCards.ts

@@ -109,8 +109,14 @@ function buildOptimisticCompanyCardCSVTransactions(
     const normalizedColumnMappings = [...columnMappings];
     const csvDataWithGeneratedIDs = csvData.map((row) => [...row]);
 
-    normalizedColumnMappings.push(CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID);
-    const externalIDColumnIndex = normalizedColumnMappings.length - 1;
+    // The backend dedupes rows by their `externalID`, so a mapped Unique ID column makes re-uploading
+    // the same file idempotent. Without one, every row gets a fresh generated ID and always imports.
+    const mappedExternalIDColumnIndex = getColumnIndex(normalizedColumnMappings, CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID);
+    const isExternalIDColumnMapped = mappedExternalIDColumnIndex >= 0;
+    if (!isExternalIDColumnMapped) {
+        normalizedColumnMappings.push(CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID);
+    }
+    const externalIDColumnIndex = isExternalIDColumnMapped ? mappedExternalIDColumnIndex : normalizedColumnMappings.length - 1;
 
     const cardNumberColumnIndex = getColumnIndex(normalizedColumnMappings, CONST.CSV_IMPORT_COLUMNS.CARD_NUMBER);
     const postedDateColumnIndex = getColumnIndex(normalizedColumnMappings, CONST.CSV_IMPORT_COLUMNS.POSTED_DATE);
@@ -125,7 +131,11 @@ function buildOptimisticCompanyCardCSVTransactions(
     const transactions: OptimisticCompanyCardCSVTransaction[] = [];
     for (const row of csvDataWithGeneratedIDs) {
         const transactionID = rand64();
-        row[externalIDColumnIndex] = transactionID;
+
+        // Fills the synthetic column, and any row whose mapped Unique ID cell is blank.
+        if (!row.at(externalIDColumnIndex)?.trim()) {
+            row[externalIDColumnIndex] = transactionID;
+        }
 
         const cardName = row.at(cardNumberColumnIndex)?.trim();
         const rawPostedDate = row.at(postedDateColumnIndex)?.trim();

src/libs/actions/ImportSpreadsheet.ts

@@ -222,6 +222,14 @@ function applyCompanyCardSavedColumnMappings(spreadsheetData: string[][], savedC
         if (role === CONST.CSV_IMPORT_COLUMNS.IGNORE || !validRoles.has(role)) {
             continue;
         }
+
+        // A saved externalID index is ambiguous: the company cards import appends a synthetic externalID column
+        // when the user maps no Unique ID, and that index is indistinguishable from a Unique ID the user mapped to
+        // the last column. Restoring it could point Unique ID at an unrelated column of the new file, whose repeated
+        // values would make the backend dedupe valid transactions, so leave it for the user to map.
+        if (role === CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID) {
+            continue;
+        }
         const index = Number(indexValue);
         if (!Number.isInteger(index) || index < 0 || index >= numColumns) {
             continue;

src/pages/workspace/companyCards/addNew/CompanyCardsImportedPage.tsx

@@ -55,6 +55,7 @@ function getCompanyCardImportColumnRoles(translate: LocaleContextProps['translat
         {text: translate('workspace.companyCards.addNewCard.csvColumns.comment'), value: CONST.CSV_IMPORT_COLUMNS.COMMENT},
         {text: translate('workspace.companyCards.addNewCard.csvColumns.category'), value: CONST.CSV_IMPORT_COLUMNS.CATEGORY},
         {text: translate('workspace.companyCards.addNewCard.csvColumns.tag'), value: CONST.CSV_IMPORT_COLUMNS.TAG},
+        {text: translate('workspace.companyCards.addNewCard.csvColumns.uniqueID'), value: CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID},
     ];
 }
 

tests/actions/CompanyCardsImportTest.ts

@@ -1,4 +1,5 @@
 import {importCSVCompanyCards} from '@libs/actions/CompanyCards';
+import type {ImportCSVCompanyCardsParams} from '@libs/API/parameters';
 import {WRITE_COMMANDS} from '@libs/API/types';
 
 import CONST from '@src/CONST';
@@ -15,6 +16,8 @@ const POLICY_ID = 'POLICY_1';
 const DOMAIN_ACCOUNT_ID = 777;
 const CSV_FEED = CONST.COMPANY_CARD.FEED_BANK_NAME.CSV;
 
+const isImportCSVCompanyCardsParams = (value: unknown): value is ImportCSVCompanyCardsParams => typeof value === 'object' && value !== null && 'settings' in value && 'csvData' in value;
+
 OnyxUpdateManager();
 describe('actions/CompanyCards importCSVCompanyCards', () => {
     beforeAll(() => {
@@ -107,4 +110,92 @@ describe('actions/CompanyCards importCSVCompanyCards', () => {
 
         apiWriteSpy.mockRestore();
     });
+
+    describe('externalID', () => {
+        const sentImports: ImportCSVCompanyCardsParams[] = [];
+
+        beforeEach(() => {
+            sentImports.length = 0;
+            jest.spyOn(require('@libs/API'), 'write').mockImplementation((...args: unknown[]) => {
+                const parameters = args.at(1);
+                if (isImportCSVCompanyCardsParams(parameters)) {
+                    sentImports.push(parameters);
+                }
+                return Promise.resolve();
+            });
+        });
+
+        afterEach(() => {
+            jest.restoreAllMocks();
+        });
+
+        it('appends a generated externalID column when no unique ID column is mapped', () => {
+            // Given an import that maps no unique ID column
+            // When the file is imported
+            importCSVCompanyCards({
+                policyID: POLICY_ID,
+                domainAccountID: DOMAIN_ACCOUNT_ID,
+                layoutName: 'My Layout',
+                layoutType: CSV_FEED,
+                columnMappings: ['cardNumber', 'postedDate', 'merchant', 'amount', 'currency'],
+                csvData: [
+                    ['Card', 'Date', 'Merchant', 'Amount', 'Currency'],
+                    ['1234', '01/15/2024', 'Coffee Shop', '-5.00', 'USD'],
+                ],
+                workspaceCardFeeds: undefined,
+            });
+
+            // Then an externalID column is appended to the mappings and every row is filled with a generated ID
+            expect(sentImports.at(0)?.settings ?? '').toContain('"columnMappings":["cardNumber","postedDate","merchant","amount","currency","externalID"]');
+            expect(sentImports.at(0)?.csvData ?? '').toMatch(/,"USD","\d+"]/);
+        });
+
+        it('sends the mapped unique ID column values as externalID so re-imports can be deduped', () => {
+            // Given an import that maps a unique ID column
+            // When the file is imported
+            importCSVCompanyCards({
+                policyID: POLICY_ID,
+                domainAccountID: DOMAIN_ACCOUNT_ID,
+                layoutName: 'My Layout',
+                layoutType: CSV_FEED,
+                columnMappings: ['externalID', 'cardNumber', 'postedDate', 'merchant', 'amount', 'currency'],
+                csvData: [
+                    ['Unique ID', 'Card', 'Date', 'Merchant', 'Amount', 'Currency'],
+                    ['txn-abc-1', '1234', '01/15/2024', 'Coffee Shop', '-5.00', 'USD'],
+                    ['txn-abc-2', '1234', '01/16/2024', 'Book Store', '-10.00', 'USD'],
+                ],
+                workspaceCardFeeds: undefined,
+            });
+
+            // Then no externalID column is appended and the mapped values are sent as-is, so the backend can dedupe a re-upload
+            expect(sentImports.at(0)?.settings ?? '').toContain('"columnMappings":["externalID","cardNumber","postedDate","merchant","amount","currency"]');
+            expect(sentImports.at(0)?.csvData ?? '').toBe(
+                JSON.stringify([
+                    ['Unique ID', 'Card', 'Date', 'Merchant', 'Amount', 'Currency'],
+                    ['txn-abc-1', '1234', '2024-01-15', 'Coffee Shop', '-5.00', 'USD'],
+                    ['txn-abc-2', '1234', '2024-01-16', 'Book Store', '-10.00', 'USD'],
+                ]),
+            );
+        });
+
+        it('falls back to a generated externalID for rows with an empty unique ID value', () => {
+            // Given an import that maps a unique ID column, with a row missing its value
+            // When the file is imported
+            importCSVCompanyCards({
+                policyID: POLICY_ID,
+                domainAccountID: DOMAIN_ACCOUNT_ID,
+                layoutName: 'My Layout',
+                layoutType: CSV_FEED,
+                columnMappings: ['externalID', 'cardNumber', 'postedDate', 'merchant', 'amount', 'currency'],
+                csvData: [
+                    ['Unique ID', 'Card', 'Date', 'Merchant', 'Amount', 'Currency'],
+                    ['   ', '1234', '01/15/2024', 'Coffee Shop', '-5.00', 'USD'],
+                ],
+                workspaceCardFeeds: undefined,
+            });
+
+            // Then that row is sent with a generated ID instead of the blank value
+            expect(sentImports.at(0)?.csvData ?? '').toMatch(/\["\d+","1234",/);
+        });
+    });
 });

tests/unit/CompanyCardsCSVImportTest.ts

@@ -30,6 +30,8 @@ describe('Company card CSV import column roles', () => {
                 CONST.CSV_IMPORT_COLUMNS.COMMENT,
                 CONST.CSV_IMPORT_COLUMNS.CATEGORY,
                 CONST.CSV_IMPORT_COLUMNS.TAG,
+                // The Unique ID column the backend dedupes re-uploads on:
+                CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID,
             ]),
         );
     });

tests/unit/ImportSpreadsheetTest.ts

@@ -1,4 +1,4 @@
-import {setSpreadsheetData} from '@libs/actions/ImportSpreadsheet';
+import {applyCompanyCardSavedColumnMappings, setSpreadsheetData} from '@libs/actions/ImportSpreadsheet';
 
 import CONST from '@src/CONST';
 import ONYXKEYS from '@src/ONYXKEYS';
@@ -25,6 +25,10 @@ function isImportedSpreadsheet(value: unknown): value is ImportedSpreadsheet {
     return typeof value === 'object' && !!value && 'data' in value;
 }
 
+function hasColumnMappings(value: unknown): value is {columns: Record<number, string>} {
+    return typeof value === 'object' && !!value && 'columns' in value;
+}
+
 /** Replays the column-major to row-major transpose the company cards import runs when Import is pressed. */
 function transposeBackToRows(columns: string[][]): string[][] {
     const rows: string[][] = [];
@@ -127,4 +131,56 @@ describe('ImportSpreadsheet', () => {
             expect(storedSpreadsheet).toBeUndefined();
         });
     });
+
+    describe('applyCompanyCardSavedColumnMappings', () => {
+        let mergedColumns: Record<number, string> | undefined;
+
+        beforeEach(() => {
+            mergedColumns = undefined;
+            jest.spyOn(Onyx, 'merge').mockImplementation((key, value) => {
+                if (key === ONYXKEYS.IMPORTED_SPREADSHEET && hasColumnMappings(value)) {
+                    mergedColumns = value.columns;
+                }
+                return Promise.resolve();
+            });
+        });
+
+        afterEach(() => {
+            jest.restoreAllMocks();
+        });
+
+        const spreadsheetColumns = [
+            ['Card', '1234'],
+            ['Date', '2024-01-15'],
+            ['Merchant', 'Coffee Shop'],
+            ['Amount', '-5.00'],
+            ['Currency', 'USD'],
+            ['Notes', 'Team offsite'],
+        ];
+        const availableRoles = [
+            CONST.CSV_IMPORT_COLUMNS.CARD_NUMBER,
+            CONST.CSV_IMPORT_COLUMNS.POSTED_DATE,
+            CONST.CSV_IMPORT_COLUMNS.MERCHANT,
+            CONST.CSV_IMPORT_COLUMNS.AMOUNT,
+            CONST.CSV_IMPORT_COLUMNS.CURRENCY,
+            CONST.CSV_IMPORT_COLUMNS.EXTERNAL_ID,
+        ];
+
+        it('restores the saved mappings for regular roles', () => {
+            applyCompanyCardSavedColumnMappings(spreadsheetColumns, {cardNumber: '0', postedDate: '1', merchant: '2'}, availableRoles);
+
+            // Asserted as entries because integer-like object keys trip the naming-convention lint rule.
+            expect(Object.entries(mergedColumns ?? {})).toEqual([
+                ['0', CONST.CSV_IMPORT_COLUMNS.CARD_NUMBER],
+                ['1', CONST.CSV_IMPORT_COLUMNS.POSTED_DATE],
+                ['2', CONST.CSV_IMPORT_COLUMNS.MERCHANT],
+            ]);
+        });
+
+        it('never restores a saved externalID mapping, which can point at the synthetic column rather than a real one', () => {
+            applyCompanyCardSavedColumnMappings(spreadsheetColumns, {cardNumber: '0', externalID: '5'}, availableRoles);
+
+            expect(Object.entries(mergedColumns ?? {})).toEqual([['0', CONST.CSV_IMPORT_COLUMNS.CARD_NUMBER]]);
+        });
+    });
 });