Excel imports: handling duplicate rows, partial failures and safe retries
Decide whether an import creates, updates or skips records, then define whether a file, business document or independent row commits together. Retrying must use recorded outcomes and stable identities rather than recreate everything.
On this page5 sections
After a spreadsheet import fails, asking the user to correct the file and upload it again is incomplete. The application should identify what was written, what was not written and what remains uncertain, then recognize resubmitted business records. In a software development specification (Chinese), define the import mode, commit unit and error report. These decisions determine whether a corrected upload duplicates or overwrites existing work.
Choose create, update or skip before importing
A row that matches an existing record might need rejection, skipping or an update. The implementation should not infer the intended operation from the file alone. Use an agreed business key, such as organization plus external document number plus line identifier. Spreadsheet row numbers change when the file is sorted, and customer names are not necessarily unique. Business identity must remain stable across corrected files.
For updates, list the fields that may be replaced. Decide whether an empty cell means leave unchanged or clear the value. The server must also enforce whether an approved or closed record can be changed through an import. The broader data integration guide explains connection options, but supporting Excel by itself does not define any of these write rules.
A passed preview is not permanent permission to write
We recommend validating the file structure, required fields, types, duplicates within the file, existing-record matches, related objects and the user's permissions. Define identifiers, leading zeros, date formats, units and decimal precision in the template instead of guessing conversions. Microsoft's Excel import guidance identifies conversion errors and duplicate-key problems. That product example supports checking such conditions; it does not dictate how a custom application should resolve them.
Between preview and submission, another person may modify a record or remove the uploader's permission. Recheck conditions that affect the write when committing. Return a specific conflict if something relevant has changed. A green preview based on outdated permissions or different rules from the actual import creates an expectation that the system cannot safely honor.
Decide what must succeed together
If a workbook contains several orders, first decide whether each order header and all its lines form one indivisible unit. Row-level success should not leave an incomplete order simply because it was easier to implement. Choose a boundary based on business relationships rather than file size. The following alternatives describe possible contracts, not mandatory rules for every application.
| Commit unit | Suggested failure outcome | When to consider it |
|---|---|---|
| Entire file | A blocking error prevents all writes | The batch must remain consistent as a whole |
| One business document | That document fails; unrelated documents may commit | Headers and lines have a strong relationship |
| One independent record | Each record has its own outcome | No relationship requires the records to succeed together |
The PostgreSQL transaction guide explains commit, rollback and savepoints. Having those mechanisms does not establish the correct business boundary. Nor should database rollback be treated as a promise to retract an external notification that has already been sent. Acceptance should inspect stored records and the agreed follow-up actions together.
Test retry behavior with a partial result
Consider a hypothetical upload of 100 independent records: 92 committed, five failed validation and three have uncertain outcomes after the response was interrupted. Preserve the task identifier, original row number, business key, state and reason. The five invalid rows can be corrected and submitted again. First investigate the three uncertain rows through the existing task rather than assume they failed and create new records.
We recommend an error export containing only rows that need correction while retaining the original task reference. If a user accidentally uploads the complete file again, completed records must still follow the chosen matching rule. Record before-and-after values for updates and link a correction task to its predecessor. Returning after a timeout should reveal the earlier task, not only an empty upload form that encourages starting again.
Review resubmission, concurrency and later reversal
- Submit the same file twice, then sort it differently and resubmit. Confirm that no unintended records appear.
- Correct failed rows and retry. Confirm that completed rows are neither executed again nor silently overwritten.
- After preview, have another account edit a target record. Check that submission recognizes the agreed conflict.
- Interrupt a task and reopen its results. Reconcile committed, uncommitted and uncertain outcomes with actual records.
A later undo action needs its own scope. Once imported records have been approved or referenced by subsequent work, deleting the whole batch may no longer be appropriate. Identify which states permit reversal and how dependent records require individual handling. Use the cross-system ownership guide to assign responsibility for external identifiers and related objects, so import behavior follows the actual business rather than the shape of a spreadsheet.