13. Import & Export

NkapBooks provides comprehensive tools for importing data into and exporting data out of the application. The Import Wizard supports bulk CSV imports with column mapping and validation, the Export Wizard lets you export any list view to CSV or JSON, reports can be exported directly, and the Backup Manager handles automatic daily database backups to the NkapBooks server.

13.0 Import & Export Overview

NkapBooks handles data movement through four distinct mechanisms:

┌──────────────────────────────────────────────────────────────┐
│  1. Import Wizard (CSV → Documents)                           │
│     Bulk create documents from structured CSV files           │
├──────────────────────────────────────────────────────────────┤
│  2. Export Wizard (Documents → CSV/JSON)                      │
│     Export list views with field selection and filters         │
├──────────────────────────────────────────────────────────────┤
│  3. Report Export (Reports → CSV)                             │
│     Export any report directly from the report toolbar         │
├──────────────────────────────────────────────────────────────┤
│  4. Database Backup (SQLite/PostgreSQL → Server)              │
│     Automatic daily backup with server-side retention          │
└──────────────────────────────────────────────────────────────┘

Key Principles

• Offline-first — All import/export operations work without an internet connection (except server backup uploads)
• Non-destructive — Imports create new documents; they never overwrite existing records
• Validated — Imports go through multiple validation stages (column mapping, cell validation, link checking) before data is committed
• Flexible — Export any combination of fields in CSV or JSON format

13.1 Import Wizard

The Import Wizard allows you to bulk-create documents from CSV files. It supports all major document types and handles both simple (flat) and complex (parent + child table) schemas.

Importable Document Types

How to Access

1. Sidebar: Navigate to Setup → Import Wizard
2. Command Palette: Press Ctrl+K (or Cmd+K on macOS) and search for "Import Wizard"
3. Direct URL: Navigate to /import-wizard in the app

Import Flow

The complete import process follows these steps:

┌────────────┐    ┌────────────┐    ┌────────────┐    ┌────────────┐    ┌────────────┐
│  1. Select │───▶│  2. Upload │───▶│  3. Map    │───▶│  4. Review │───▶│  5. Import │
│  Doc Type  │    │  CSV File  │    │  Columns   │    │  & Validate│    │  & Report  │
└────────────┘    └────────────┘    └────────────┘    └────────────┘    └────────────┘

Step 1: Select Document Type

When you open the Import Wizard, the first step is selecting the type of document you want to import:

• Click the document type dropdown at the top of the page
• Select from the list of available schemas (e.g., Item, Party, Sales Invoice)
• The wizard automatically loads the schema definition and builds the available field list

Step 2: Upload CSV File or Add Rows Manually

You have two options for getting data into the wizard:

Option A — Upload a CSV file:

1. Click Select File in the header toolbar
2. Browse to your .csv file and select it
3. The wizard parses the CSV and attempts to auto-map columns based on header names
4. Data rows appear in the grid below

Option B — Add rows manually:

1. Click the + (Add Row) button in the header
2. Empty rows appear in the grid
3. Fill in values directly in each cell

Step 3: Map CSV Columns to Document Fields

After uploading a CSV, the wizard shows a mapping interface:

Column Picker Dialog:

The column picker groups fields by schema:

• Main document fields — Direct fields on the parent document (e.g., name, date, party)
• Child table fields — Fields in child tables (e.g., items.item, items.quantity, items.rate)
• Required fields — Checked by default and cannot be unchecked

Auto-Mapping Logic:

When a CSV is loaded, the wizard scans the first row for header labels and tries to match them against:

1. Field labels (display names)
2. Field names (technical names)
3. Schema-qualified labels (e.g., SalesInvoiceItem.item)

Step 4: Review and Validate

Before importing, review the data grid:

Error Banner:

At the top of the grid, an error message appears if:

• Duplicate column mappings exist: "Duplicate columns found: Customer, Item"
• Required fields are missing: "Required fields not selected: Date, Party"

Step 5: Import and Report

When validation passes:

1. Click the Import button (blue primary button)
2. A confirmation dialog shows the number of rows to import
3. The wizard processes rows one by one:
   • Converts raw CSV values to proper document values using the Converter
   • Creates a new document (Doc) for each row
   • For child tables, groups rows by parent name and pushes child entries
   • Saves (and optionally submits) each document
4. A progress indicator shows the current status
5. After completion, a summary report shows:
   • ✓ Successful imports — List of document names created
   • ✗ Failed imports — List of failed rows with error details

Import Actions Menu

The More dropdown menu provides additional actions:

CSV Template

The Save Template action generates a downloadable CSV file containing:

• Row 1: Schema labels (e.g., Sales Invoice, Sales Invoice Item)
• Row 2: Field labels (e.g., Customer, Date, Item, Quantity)
• Row 3: Field keys (technical names like party, date, items.item, items.quantity)

This template serves as a reference for preparing your import data in any spreadsheet application.

Handling Child Tables

When importing documents with child tables (e.g., Sales Invoice with line items):

1. Parent rows are identified by having a unique value in the name column
2. Child rows share the same parent name but have different child table values
3. The wizard automatically groups child rows under their parent

Example CSV for Sales Invoice:

In this example:

• SINV-001 has two line items (Widget A and Widget B)
• SINV-002 has one line item (Widget C)
• The customer and date only need to be specified on the first row for each parent

Option Field Handling

For fields with predefined options (Select/AutoComplete), the importer accepts both:

• Values (e.g., Male, Female)
• Labels (e.g., the translated display label)

The importer maintains a label-to-value mapping and automatically resolves labels to their correct values during import.

Tips for Successful Imports

13.2 Data Export

The Export Wizard allows you to export data from any list view in NkapBooks to CSV or JSON format with full control over which fields are included.

How to Access

1. Open any list view (e.g., Sales Invoices, Customers, Items)
2. Click the Menu (⋮) button in the list header
3. Select Export Data
4. The Export Wizard panel opens

Export Wizard Interface

The Export Wizard provides three configuration sections:

Configuration Options

Field Selection

The field selector shows all fields organized by section:

• Main Fields — Direct fields on the document (e.g., Name, Date, Status, Amount)
• Table Fields — Child table fields grouped by table name (e.g., Invoice Items, Payment References)
• Checkboxes — Each field has a checkbox to include/exclude it from the export
• Table toggle — Checking a Table field enables its child field checkboxes

A counter at the bottom shows the total number of selected fields: "12 fields selected".

Export Formats

Export Process

1. Configure options (filters, format, limit)
2. Select the fields you want to export
3. Click Export
4. Choose a save location in the file dialog
5. The file is saved and a success notification appears with an option to Open Folder to locate the file

File Naming

Exported files are automatically named using the pattern:

{document-type}_{YYYY-MM-DD}.{extension}

Examples:

• sales-invoice_2024-01-15.csv
• customer_2024-01-15.json
• item_2024-01-15.csv

13.3 Report Export

All reports in NkapBooks support direct export to CSV format.

Supported Reports

How to Export Reports

1. Navigate to any report page (e.g., Reports → General Ledger)
2. Configure filters (date range, accounts, parties, etc.)
3. Click the Export button in the report toolbar
4. Choose a save location
5. The report data is saved as a CSV file

Report PDF Printing

In addition to CSV export, reports can be printed or saved as PDF:

1. Click Print on the report toolbar
2. The report opens in a print preview
3. Use your system print dialog to save as PDF or send to a printer

13.4 PDF Document Export

Individual documents can be exported to PDF using the print template system. This is covered in detail in Section 12: Print & Templates, but here is a quick summary:

Supported Documents for PDF Export

PDF Export Flow

1. Open any supported document
2. Click Print → Save as PDF (or use the keyboard shortcut)
3. Choose a save location
4. The document is rendered using its assigned print template and saved as a PDF file

13.5 Database Backup

NkapBooks includes an automatic Backup Manager that handles daily database backups to the NkapBooks server. This ensures your financial data is safely stored off-device in case of hardware failure or data loss.

Architecture

The Backup Manager operates through the Tauri (Rust) backend:

┌────────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│  Backup Manager    │───▶│  Tauri Backend    │───▶│  NkapBooks       │
│  (TypeScript)      │    │  (Rust Commands)  │    │  Server          │
│                    │    │                    │    │                    │
│  • Scheduling      │    │  • export_database │    │  • Store backup   │
│  • Status tracking │    │    _backup         │    │  • One per customer│
│  • Error handling  │    │  • upload_database │    │  • Auto-replace   │
│                    │    │    _backup         │    │    old backups    │
└────────────────────┘    └──────────────────┘    └──────────────────┘

How It Works

1. Startup: When the app starts and a database is connected, the Backup Manager begins
2. Initial Check: After a 30-second delay (to let the app finish loading), it checks if a backup is due
3. Periodic Checks: Every 1 hour, it checks whether 24 hours have passed since the last successful backup
4. Export: If a backup is due, the Rust backend exports the database:
   • SQLite: Copies the .db file
   • PostgreSQL: Performs a SQL dump
5. Upload: The exported file is uploaded to the NkapBooks server with metadata
6. Retention: The server retains exactly one backup per customer — each new backup replaces the previous one

Backup Metadata

Each backup upload includes metadata for identification and troubleshooting:

Backup Status

The Backup Manager tracks its operational status:

Manual Backup

In addition to automatic backups, you can trigger a manual backup:

1. Navigate to Settings
2. The backup status shows the last backup time and next scheduled check
3. Click Backup Now to trigger an immediate backup

Database File Access

For advanced users, the database file can also be accessed directly:

The database file location is shown in the Database Selector screen when you select or create a database.

Backup Scheduling Constants

Backup Availability

13.6 Data Migration Tips

Migrating from Another Accounting System

When migrating from another accounting application, follow this recommended order:

1. Chart of Accounts — Import your account structure first
2. Parties (Customers & Suppliers) — Import all customer and supplier records
3. Items — Import your product/service catalog
4. Opening Balances — Use Journal Entries to set opening balances for all accounts
5. Historical Invoices — Import past invoices if needed for reporting continuity
6. Payments — Import payment records linked to the imported invoices

Data Preparation Checklist

Before importing data:

• Export data from your source system in CSV format
• Ensure all linked records exist (e.g., create customers before importing invoices that reference them)
• Standardize date formats to YYYY-MM-DD
• Remove currency symbols and thousand separators from numeric fields
• Verify that option field values match NkapBooks dropdown options
• Test with a small sample (5–10 rows) before doing the full import
• Back up your database before large imports

Common Import Errors

13.7 Quick Reference

Import Wizard Keyboard Shortcuts

Import Wizard Actions

Export Wizard Actions

Summary

The Import & Export tools in NkapBooks ensure you can always get your data in and out of the application efficiently. Whether you're migrating from another system, sharing data with your accountant, or ensuring disaster recovery with automatic backups, NkapBooks has you covered.