Data Import/Export — User Manual

Audience: System administrators
Version: 1.0 — November 2026
Module: Mod-Exim


Table of Contents

  1. Introduction
  2. Getting Started
  3. Importing Data
  4. Exporting Data
  5. Supported Record Types
  6. Workbook Format & Templates
  7. Error Handling & Recovery
  8. Common Workflows
  9. Troubleshooting

1. Introduction

The Data Import/Export module (Exim) allows bulk upload and download of contacts, clients, matters, bank accounts, and other key records. Use it to:

Key Features


2. Getting Started

Opening the Import/Export Window

  1. In the main menu, click Administration → Data Management → Import/Export.
  2. The Data Import/Export window opens.

Main Screen Layout

The screen has two tabs:

Each tab has:


3. Importing Data

Import Workflow

  1. Open the Import tab.
  2. Select the Record Type (e.g., Contacts, Clients, Matters).
  3. Click Browse and select your spreadsheet file (.xlsx, .xls, .csv, or .ods).
  4. The Preview pane shows:
    • The headers detected
    • A sample of the first few rows
    • Any validation warnings (missing required fields, invalid values)
  5. Review the preview. If there are errors:
    • Fix them in the spreadsheet and reload, or
    • Check Skip Row Errors if you want to import valid rows and skip invalid ones.
  6. Click Import. A progress bar shows the import running.
  7. When complete, the Result pane shows:
    • Success: N records imported
    • Failures: N rows skipped (if any)
    • A detailed Import Log listing each row's status

Import Options

Option Effect
Skip Row Errors If checked, bad rows are skipped and good rows are imported. If unchecked, any error rolls back the entire import. Default: off (fail-safe mode).
Update Existing (for Contacts) If checked, contacts matched by external ID or contact name are updated (not inserted). Default: off (new records only).
Validate Only Preview the import without writing to the database. Use this to test before committing.

Row-by-Row Validation

Each row is validated independently:

Rows with errors are reported with the sheet name, row number, and the problem (e.g., "Sheet Contacts, Row 5: Invalid client status 'active' (expected ACTIVE, INACTIVE, or ARCHIVED)").


4. Exporting Data

Export Workflow

  1. Open the Export tab.
  2. Select the Record Type (e.g., Contacts, Clients, Matters).
  3. (Optional) Set any filters (e.g., "Export only ACTIVE clients").
  4. Click Export. A file browser opens; select where to save the file.
  5. The file is saved to your computer. A Result pane shows:
    • Success: N records exported
    • File path where it was saved
    • Summary of what was included

Export Scope

Deleted records are not exported (soft-deleted contacts, clients, and matters are excluded). This ensures your export never restores a record you deliberately removed.

Child records (e.g., bank accounts linked to a contact, matters linked to a client) are exported only if their parent is included in the export.


5. Supported Record Types

Type Import Export Notes
Contacts ✓ ✓ Includes addresses, phone, email, bank accounts.
Clients ✓ ✓ Includes contact link, client type, status, reference.
Matters ✓ ✓ Includes client, matter type, status, parties, dates. Refuses to move a matter with trust/ledger entries to another client.
Bank Accounts ✓ ✓ Linked to a contact (the account holder).
FICA Records ✓ ✓ Verification status, expiry date, linked to a contact and matter.
Fee Codes ✓ ✓ Fee sheet, code, description, VAT flag, amount.
Tariff Versions ✓ ✓ Version number, effective date, linked to a tariff table.
Court Holidays ✓ ✓ Date, holiday type (public holiday, recess, etc.).

6. Workbook Format & Templates

File Format

Supported formats: Excel (.xlsx, .xls), CSV (.csv), ODS (.ods).

Column Headers

Each record type has a set of expected columns. The importer reads headers by name (not position), so columns can be in any order and you can include extra columns (they are ignored).

Example: Contacts Import

Column (Header) Required? Example Notes
Contact Name Yes John Smith Free text; must be unique per contact.
External ID No EXT-12345 Your reference number; optional but useful for reconciliation.
ID Number No 9201234567 ID passport or company registration number.
Email No john@example.com Can be blank; validated format if present.
Phone No +27 21 555 1234 Can be blank; formatted flexibly.
Address Line 1 No 123 Main Street Full address; can span multiple rows if the importer supports wrap.
Type No PERSON Contact type: PERSON or ORGANISATION.

Example: Clients Import

Column (Header) Required? Example Notes
Client Name Yes Acme Corp Unique; the display name.
Client Type Yes CORPORATE CORPORATE, INDIVIDUAL, GOVERNMENT, NGO, etc.
Status Yes ACTIVE ACTIVE, INACTIVE, or ARCHIVED.
Contact ID / Reference Yes 12345 or EXT-ABC Links the client to an existing contact.

Cell Format Rules

Headers Are Case-Insensitive

These are all read as the same column:


7. Error Handling & Recovery

Validation Errors During Import

If validation finds problems, the Import Preview shows:

Two Modes: Fail-Safe vs. Skip

  1. Fail-Safe (default): Any error aborts the entire import. No records are written. Use this for critical data where you want to fix all errors before committing.

  2. Skip Row Errors: Rows with errors are skipped; valid rows are imported. Use this for large bulk imports where a few bad rows are acceptable.

Recovering from a Failed Import

If an import fails:

  1. Fix the errors in the source spreadsheet.
  2. Re-import the corrected file.
  3. If the file had some valid rows mixed with bad ones (now re-imported), duplicates are prevented by:
    • Unique constraint checking (matched by name or external ID)
    • Mandatory notes on imports (a reason is recorded so you can trace it)

8. Common Workflows

Scenario: Onboarding 200 Contacts from an Old System

  1. Export contacts from the old system as a CSV.
  2. In ATA, open Import and select Contacts.
  3. Upload the CSV.
  4. The preview shows missing columns or unrecognized values. Amend the CSV and re-upload.
  5. Once validation passes, enable Skip Row Errors (some contacts may have incomplete data you cannot fix).
  6. Click Import. Rows with all required fields are imported; rows missing a required field (e.g., name) are skipped with a reason.
  7. Review the Import Log to see which rows failed and why.
  8. Manually add the failed rows later, or fix the source data and re-import.

Scenario: Bulk Update Client Status (ACTIVE → INACTIVE)

  1. Open Export, select Clients, and run the export. Clients are written to a spreadsheet.
  2. Open the spreadsheet in Excel/Sheets. Find the Status column and change selected rows to INACTIVE.
  3. Save the file.
  4. Open Import, select Clients, and upload the edited file.
  5. Enable Update Existing so that clients matched by name are updated, not inserted as new.
  6. Click Import. The statuses are updated for matched clients.

Scenario: Backup All Contacts Before a System Migration

  1. Open Export, select Contacts, and run the export.
  2. Save the file with a timestamp (e.g., contacts_backup_2026-11-15.xlsx).
  3. Keep the file as a backup. If data is lost, you can re-import it.

9. Troubleshooting

Q: The import preview says "Invalid client status." What are the valid values?

A: The valid statuses for a record type are listed in the validation error. For clients, the valid values are:

Type these exactly as shown (uppercase, no spaces).


Q: I exported contacts, edited them, and re-imported them. Why are there duplicates now?

A: By default, the importer creates new records, not updates. To update existing records:

  1. Open Import → Contacts.
  2. Check Update Existing.
  3. Re-import the file.

Matched contacts (by name or external ID) are updated; unmatched ones are inserted as new.


Q: The importer says "Row 5: Cannot move matter to another client" and refuses to import. Why?

A: A matter with trust ledger entries, active reservations, or draft journal entries cannot be reassigned to a different client because the financial entries are tied to the original client. To move the matter:

  1. Clear all trust/draft entries first (settle any trust, void drafts).
  2. Then re-import.

Alternatively, do not change the client for that matter in the import.


Q: My spreadsheet has dates written as DD/MM/YYYY. Will they import correctly?

A: Not reliably. A date such as 01/02/2026 could be 1 February or 2 January, so the importer does not guess. Text dates must be written year first:


Q: The file is 60 MB and the importer says "File too large." What should I do?

A: The file size limit is 50 MB. To reduce file size:

  1. Split the data into multiple sheets/files (e.g., Sheet 1 with rows 1–500, Sheet 2 with rows 501–1000).
  2. Import each file separately.

Or, remove unnecessary columns (e.g., internal notes, unused fields) to shrink the file.


Q: I accidentally exported and overwrote my original data file. Can I recover it?

A: The export runs as of "now" (the current state of the database). If you want a backup:

  1. Export regularly and save backups with timestamps.
  2. Use version control or cloud storage to keep multiple versions.

The export itself does not replace or delete the original file unless you explicitly save it there.


Q: Which users can import/export?

A: Importing and exporting are restricted to system administrators (the CAN_IMPORT_DATA and CAN_EXPORT_DATA permissions). Both are checked when you import or export, and without a signed-in administrator the action is refused. Downloading a blank template needs neither.

Contact your system administrator if you need data imported or exported.