Data Import/Export — User Manual
Audience: System administrators
Version: 1.0 — November 2026
Module: Mod-Exim
Table of Contents
- Introduction
- Getting Started
- Importing Data
- Exporting Data
- Supported Record Types
- Workbook Format & Templates
- Error Handling & Recovery
- Common Workflows
- 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:
- Onboard a large number of contacts or clients from spreadsheets
- Migrate data from another practice management system
- Backup data by exporting to a spreadsheet
- Update records in bulk (e.g., change multiple client statuses at once)
- Reconcile data between ATA and an external system
Key Features
- Selective import — choose which records to import; skip rows with errors and continue
- Validation — detects missing required fields, invalid statuses, and data-type mismatches before importing
- Audit trail — every imported or exported record is logged with the date, user, and action
- Soft-delete respect — does not restore soft-deleted contacts, clients, or matters
- Atomic savepoints — if "skip row errors" is on, bad rows are skipped and good ones are committed; otherwise, any error rolls back the entire import
2. Getting Started
Opening the Import/Export Window
- In the main menu, click Administration → Data Management → Import/Export.
- The Data Import/Export window opens.
Main Screen Layout
The screen has two tabs:
- Import — bulk upload from a spreadsheet
- Export — bulk download to a spreadsheet
Each tab has:
- A Record Type selector (Contacts, Clients, Matters, Bank Accounts, etc.)
- A File Browser to select your workbook
- Import/Export Options (validation rules, error handling, etc.)
- A Preview or Result pane showing what will be or was imported/exported
3. Importing Data
Import Workflow
- Open the Import tab.
- Select the Record Type (e.g., Contacts, Clients, Matters).
- Click Browse and select your spreadsheet file (
.xlsx,.xls,.csv, or.ods). - The Preview pane shows:
- The headers detected
- A sample of the first few rows
- Any validation warnings (missing required fields, invalid values)
- 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.
- Click Import. A progress bar shows the import running.
- 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:
- Required fields must have values (e.g., contact name, client type).
- Status codes must be valid (e.g., "ACTIVE", "INACTIVE", not "active" or "active ").
- Data types must match (e.g., a phone number field must have a number or formatted phone, not "N/A").
- Foreign keys must exist (e.g., a matter's client must already be in the database).
- Uniqueness constraints must be satisfied (e.g., a contact's external ID cannot be a duplicate).
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
- Open the Export tab.
- Select the Record Type (e.g., Contacts, Clients, Matters).
- (Optional) Set any filters (e.g., "Export only ACTIVE clients").
- Click Export. A file browser opens; select where to save the file.
- 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).
- File size limit: 50 MB
- Encoding: UTF-8 (for CSV)
- Sheet name: The main sheet (first sheet) is read; other sheets are ignored (future enhancement: multi-sheet support).
- Headers: Case-insensitive, must be present in row 1.
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. |
| 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
- Text fields: Plain text (no formulas).
- Numeric fields: Numbers (not text); read at their exact value (a 13-digit ID in a General cell is read correctly, not as scientific notation).
- Dates: ISO format preferred (
YYYY-MM-DD), but day-first and month-first formats are interpreted based on heuristics. Avoid ambiguous formats like01/02/03. - Boolean/Status fields: Uppercase codes (
ACTIVE,VERIFIED, etc.); not yes/no or true/false. - Formulas: Cached values are read (the result of a formula), not the formula itself.
Headers Are Case-Insensitive
These are all read as the same column:
Contact Namecontact nameCONTACT NAMEContact_Name
7. Error Handling & Recovery
Validation Errors During Import
If validation finds problems, the Import Preview shows:
- Error count at the top
- Detailed errors listed by row (e.g., "Row 5: Status 'active' not recognized; expected ACTIVE or INACTIVE")
- Suggested fixes (e.g., "Did you mean ACTIVE?")
Two Modes: Fail-Safe vs. Skip
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.
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:
- Fix the errors in the source spreadsheet.
- Re-import the corrected file.
- 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
- Export contacts from the old system as a CSV.
- In ATA, open Import and select Contacts.
- Upload the CSV.
- The preview shows missing columns or unrecognized values. Amend the CSV and re-upload.
- Once validation passes, enable Skip Row Errors (some contacts may have incomplete data you cannot fix).
- Click Import. Rows with all required fields are imported; rows missing a required field (e.g., name) are skipped with a reason.
- Review the Import Log to see which rows failed and why.
- Manually add the failed rows later, or fix the source data and re-import.
Scenario: Bulk Update Client Status (ACTIVE → INACTIVE)
- Open Export, select Clients, and run the export. Clients are written to a spreadsheet.
- Open the spreadsheet in Excel/Sheets. Find the Status column and change selected rows to
INACTIVE. - Save the file.
- Open Import, select Clients, and upload the edited file.
- Enable Update Existing so that clients matched by name are updated, not inserted as new.
- Click Import. The statuses are updated for matched clients.
Scenario: Backup All Contacts Before a System Migration
- Open Export, select Contacts, and run the export.
- Save the file with a timestamp (e.g.,
contacts_backup_2026-11-15.xlsx). - 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:
ACTIVE— client is current and activeINACTIVE— client is dormant or not in active workARCHIVED— client is closed and should not appear in most lists
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:
- Open Import → Contacts.
- Check Update Existing.
- 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:
- Clear all trust/draft entries first (settle any trust, void drafts).
- 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:
- Use ISO format:
YYYY-MM-DD(e.g.,2026-11-15). - A cell that Excel holds as a real date is read correctly whatever its display format.
- A date typed as day/month/year text is reported with its sheet and row so you can correct it.
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:
- Split the data into multiple sheets/files (e.g., Sheet 1 with rows 1–500, Sheet 2 with rows 501–1000).
- 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:
- Export regularly and save backups with timestamps.
- 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.