Skip to main content

Data Import & Onboarding

If you are migrating from another system — or setting up a new tenant — the Data Import tool lets you bulk-load your master data and opening balances without entering records one by one.

Go to Settings → System → Data Import to access the tool.

How it works​

Every entity follows the same three-step flow:

  1. Download the template — an Excel file with column headers, field notes in row 2, and sample rows
  2. Fill in your data — replace the sample rows with your real data; do not change the headers in row 1
  3. Upload and review — the system validates every row and shows a colour-coded result table before you apply

Only rows that pass validation are imported. Rows with errors or duplicates are skipped and shown with a specific error message — you can correct the file and re-upload.

What you can import​

Master data​

Import master data first — transactions reference these records.

EntityKey fieldsNotes
CustomersName, PhoneName must be unique
VendorsName, Type, PhoneType must be: Fuel · Maintenance · Border Agent · Spare Parts · Subcontractor · Other
DriversName, License Number, License Expiry, Phone, StatusLicense Expiry in YYYY-MM-DD; Status: Active · On Trip · On Leave · Suspended. Optional Truck / Trailer columns take a vehicle's Reg Number and auto-assign the driver to it — import Fleet first, since the lookup only matches existing, non-deleted vehicles of the matching type
FleetReg Number, Type, Make, ModelType: Truck · Trailer
RoutesName, Origin, Destination, Distance (km), Estimated DaysCheckpoints optional — semicolon-separated (e.g. Mikumi;Iringa;Mbeya)
Chart of AccountsAccount No, Name, Category, Type, Debit/CreditSupplements the Tanzania Standard CoA — existing accounts are never overwritten
ItemsCode, Name, Type, Unit, Selling Price, VAT AppliedType: Product · Service; VAT Applied: true · false. Optional columns: Description, Barcode (must be unique across your catalog), Brand, Menu Category (Food · Beverage, for Restaurant POS), Item Category (must match Settings → Invoicing & Tax → Item Categories), Store(s) (comma-separated store names; blank = sells at every store), Cost Price, Revenue/Expense Account No (validated against your Chart of Accounts), Expense Category, Status (Active · Inactive, defaults to Active), Variant Group Code and Variant Label (see below). Barcode, Brand, Menu Category, Item Category, Store(s) and the variant columns apply to Products only and are ignored on Service rows
Fixed AssetsName, Category, Acquisition Date, Acquisition Cost, Depreciation Method, StatusTRA Class is optional and auto-fills the depreciation method and rate if provided
RoomsRoom Number, Room Type CodeHotel Management only. Room Type Code must match a room type you've already added on the Rooms page. Optional: Floor, Property (defaults to your main property), Housekeeping Status (defaults to Clean), Known Issues
LeadsBusiness Name, Phone, Status, Assigned Rep, Package InterestInternal-only — only appears for tenants with Field Activity's Sales Playbook enabled; see Permissions for why lead.* isn't in the general permission set

Item variants (sizes, colours): to group the sizes or colours of one style, give those rows the same Variant Group Code (for example SHOE-001) and put what makes each row different in Variant Label (for example Size 40). Codes are matched regardless of upper/lower case. A code that doesn't exist yet creates the variant group, named after the first row's item name. Each size is still its own item with its own Code and Barcode. A Variant Label without a Variant Group Code on the same row is an error. Leave both blank for an item with no variants.

Updating existing Items: Items is the one entity that supports re-uploading against records you've already created. Tick Update existing records on the upload step and a row whose Code matches an existing item fills in that item's blank optional fields from the file — Description, Barcode, Brand, Menu Category, Item Category, Cost Price, Revenue/Expense Account No and Expense Category; Store(s) only if the item has no store assignment yet; and a variant group only if the item isn't already in one (an item is never moved to a different group). A field the item already has a value for is never overwritten, and required fields (Name, Type, Unit, Selling Price, VAT Applied, Status) are left alone entirely even if the file's value differs. Rows matching an existing item are marked Update on the review screen. Off by default; every other entity is always skip-if-exists.

Each entity has its own licensing requirement — an entity missing from your import screen almost always means a licensing gap, not a bug:

  • Chart of Accounts, Opening Balances — require the Accounting module
  • Items, Vendor Invoices — require Accounting, Point of Sale, or Spare Parts (any one is enough), or Diesel Yard
  • Fixed Assets — requires the Assets module specifically (having Accounting alone isn't enough)
  • Stock Levels — requires Point of Sale or Spare Parts, or Diesel Yard
  • Rooms — requires Hotel Management with Room Management turned on

Transactions (migration)​

Use these to carry over open records from your previous system.

EntityWhat it createsNotes
Customer InvoicesCustomer invoicesCustomer Name must match an existing customer — import Customers first
QuotationsQuotationsClient Name is matched to an existing customer if found, but is not required to exist — free text is fine
Vendor InvoicesVendor bills (purchase invoices)Vendor Name must match an existing vendor — import Vendors first
Opening BalancesA single Draft journal entryAll rows become lines in one journal — review and post it in Accounting → Journal Entries
Stock LevelsStock ledger entriesItem Code must match an existing Product-type Item — import Items first

Validation rules​

The system checks each row before applying:

CheckWhat fails
Required fieldsRow with an empty required column is rejected
Enum valuesValue not in the allowed list (e.g. wrong Status) is rejected
Numeric fieldsNon-numeric value where a number is expected
Date formatDate not in YYYY-MM-DD format
Boolean fieldsValue that is not true or false
Lookup fieldsA value that has to match an existing record isn't found — e.g. Customer Name, Vendor Name, Account No, driver Truck or Trailer Reg Number, Item Code, Store, Expense Category, Item Category, Room Type Code, or a lead's Assigned Rep
DuplicatesRecord with the same key already in the system — skipped with a warning (unless Update existing records is ticked for Items)
Batch duplicatesTwo rows in the same file with the same key — the second one is an error
Barcode clashesAn item Barcode already used by a different item, or repeated in the same file — that row is an error

Opening balances​

Opening balances represent your GL account balances at the point you switch to this system. They are imported differently from other entities:

  • Each row in the template becomes one journal line
  • All lines are combined into a single Draft journal entry named Opening Balances Import
  • The journal is created in Draft status — you can review it in Accounting → Journal Entries
  • Check that total Debits equal total Credits (the review screen shows both totals)
  • When satisfied, click Post to lock the opening balances into the General Ledger
Balance your opening journal

If your opening balances do not balance (total debits ≠ total credits), investigate before posting. Common causes: missing retained earnings account, transfers or owner equity not accounted for.

Follow this sequence to avoid lookup errors between entities:

1. Customers
2. Vendors
3. Drivers
4. Fleet
5. Routes
6. Chart of Accounts  (or use Tanzania Standard CoA seed)
7. Items
8. Fixed Assets
9. Rooms              (Hotel Management — add room types first)
10. Opening Balances  → review draft journal → post
11. Stock Levels      (opening counts, once Items and Stores exist)
12. Customer Invoices (outstanding / pending invoices)
13. Quotations        (open or historical quotes)
14. Vendor Invoices   (unpaid vendor bills)

Customer invoices — migration notes​

When migrating outstanding invoices:

  • Invoice No is optional — if blank, one is auto-generated (IMP-{timestamp}-{row})
  • Amount is the subtotal before VAT
  • VAT Rate (%) defaults to 18 if left blank; enter 0 for exempt or zero-rated services
  • Status: use Sent for unpaid invoices the customer is aware of; Draft for invoices not yet sent; Paid for historical invoices you want in the system for records; Overdue for a Sent invoice already past its due date
  • The import creates a single-line invoice — you can open any imported invoice and edit it for multiple lines

Quotations — migration notes​

When migrating open or historical quotations:

  • Quote No is optional — if blank, one is auto-generated (QT-IMP-{timestamp}-{row})
  • Client Name does not need to exist in your Customers list — if it matches an existing customer by name, the quote is linked to that customer's contact details; otherwise it's kept as plain text
  • Valid Until is required — enter the date the quote expires or expired
  • Amount is the subtotal before VAT
  • VAT Rate (%) defaults to your tenant's rate if left blank; enter 0 for exempt or zero-rated quotes
  • Status: use Sent for quotes awaiting a client response, Accepted or Rejected for decided quotes, Draft for unfinished ones, Expired for a Sent quote past its Valid Until date. Converted is not available on import — a converted quote needs a real linked job or invoice, which a plain migration can't create. Convert it manually after import if needed.
  • The import creates a single-line quotation — open any imported quote and edit it for multiple line items, or use Excel line-item import on the quote itself

Vendor invoices — migration notes​

  • Amount is the subtotal before VAT
  • VAT Applied: enter true if the vendor charged VAT; false otherwise
  • Status: Approved for bills you have already verified; Draft for unreviewed bills; Paid for settled bills
  • Approved bills are visible in AP Aging reports

Stock levels — migration notes​

Use this to set opening stock counts when onboarding a new store, or to make a bulk stocktake correction instead of adjusting items one at a time:

  • Item Code must match an existing Product-type Item — import Items first
  • Store is optional — leave it blank to use your default store; otherwise it must match an existing, active store name. Naming a store also limits that item to selling only at that store from then on — leave it blank if the item should keep selling everywhere
  • Movement Type: Opening Balance for an initial starting count, Adjustment for a correction to existing stock, or Stocktake Count when you've counted what's actually on the shelf
  • Quantity — for Opening Balance, the starting count; for Adjustment, the change as a positive/negative number (e.g. -3 for shrinkage); for Stocktake Count, your new total on hand (the system works out the difference for you)
  • Unit Cost is optional — defaults to the item's cost price if left blank
  • Reason is required on every row — it's the same audit-trail requirement as a manual stock adjustment in POS Reports
  • Every row becomes a new entry in the stock ledger — re-uploading an Opening Balance or Adjustment file adds more movements rather than overwriting, so double-check the file before importing
Stocktake shortcut

For a stocktake, click ↓ Download Current Stock (.xlsx) instead of the blank template. You get a sheet with every active product, its store, and its current on-hand count, already set to Stocktake Count. Overwrite the Quantity column with what you counted, add a Reason, and upload it.

Limits and exclusions​

The import tool does not support:

  • Historical Jobs or Trips — operational history cannot be reconstructed from a spreadsheet
  • Payments linked to specific invoices — mark invoices as Paid in the invoice import instead
  • GL Entries directly — use the Opening Balances journal flow to set GL balances

There is no hard row limit per file, but very large files (10 000+ rows) may be slow to validate in the browser. For large datasets, split into batches of 2 000–3 000 rows per file.