Upload a trial balance

Who does this: FS Preparer · Senior Accountant · Platform Admin When: You have the client's GL trial balance for the engagement period in a CSV/XLSX/XLS and want to ingest it. Result: Every TB row lands as an FsTrialBalanceItem, the engagement transitions to TB_UPLOADED, and the Auto Suggest button on the Mapping tab is enabled.

Most engagements ingest a single TB. Re-uploading is allowed but invalidates everything downstream (mappings, statements, notes) and returns the engagement to DRAFT — by design, so a reviewer can see the regression in the status badge.

Before you start

• [ ] Engagement at DRAFT. Already past DRAFT? Re-uploading is allowed but the regression to TB_UPLOADED will drop all downstream artifacts.
• [ ] TB file in CSV / XLSX / XLS, max 10 MB.
• [ ] Column headers recognisable by the smart-column detector (case-insensitive, underscore/space-agnostic):
  • account_code, description, debit, credit
  • OR account_code, description, current_year, prior_year
• [ ] No subtotal rows in the file — the parser sums every row.

TIP

If the TB exports from the client's accounting platform as "debit-positive credit-negative", the parser handles that natively. If it exports "credit-positive credit-balance" mixed columns, normalise at source — the detector can flag mixed conventions but cannot infer intent.

Steps

1. Open the engagement detail page.
2. Click Upload Trial Balance in the top right.
3. In the drag-drop zone, drop the CSV/XLSX. Single file per upload.
4. The UI shows an upload progress bar.
5. On completion the preview table appears:
   • Row count
   • Detected current-year and prior-year columns (if applicable)
   • Balance-check badge — green if Σ currentYearBalance is zero ±1.0 SGD, amber otherwise
6. Confirm. Engagement transitions DRAFT → TB_UPLOADED.

How to know it worked

1. The TB preview table appears on the engagement page; row count matches the source file.
2. The status badge moves to TB_UPLOADED; the Auto Suggest button on the Mapping tab is now enabled.
3. The activity log shows fs.tb.upload.requested then fs.tb.uploaded.

Common situations

If you see…	It means…	What to do
Balance-check badge is amber ("not balanced by SGD {n}")	Σ currentYearBalance does not equal zero after sign normalisation	Find the unbalanced rows in the source; fix at source; re-upload. See TB not balanced
Preview shows zero rows or only headers	The parser could not detect a valid column structure	Reformat the file; verify the headers match the accepted shapes. See TB parse failed
Engagement was at TB_MAPPED and the re-upload returned it to TB_UPLOADED	Re-upload deliberately invalidates mappings + statements	Re-run auto-suggest and regenerate statements
413 Payload Too Large	File > 10 MB	Strip non-essential columns and re-export from the source
Detected only one year column	The 4-digit year-header detector did not find a prior-year column	Either fine (no comparatives) or rename the prior column to a recognisable header (e.g. 2023) and re-upload

Related runbooks

• Run auto-suggest mapping — next step after TB is uploaded
• FS-02 userflow — API trace, DB verification, negative cases
• Financial Statements SOP §6 / Step 2.0
• TB not balanced
• TB parse failed