Skip to main content

📥 Importing Data (CSV)

The Importing Data (CSV) tool allows you to quickly add or update large amounts of data using a spreadsheet file. It’s designed for power users who want speed and control without sacrificing data accuracy.

You can use CSV imports to create new records, update existing ones, or do both at the same time.

What Is CSV Import?​

CSV import lets you upload a spreadsheet (.csv file) and map its columns to fields in the system.

Common use cases include:

  • Importing clients, projects, vendors, or employees
  • Migrating data from another system
  • Making bulk updates that would be slow to do manually
  • Cleaning up or standardizing records

Where You’ll Find It​

CSV import is available anywhere data tables are used, such as:

  • Table widgets
  • Quick Actions menus

Look for the Import CSV action in table headers or menus.

The Import Process (Overview)​

Importing data follows the same basic steps every time:

  1. Select a target table
  2. Upload a CSV file
  3. Map CSV columns to table fields
  4. Choose how conflicts are handled
  5. Preview the data
  6. Confirm and run the import

Each step is explained below.

Step 1: Select a Table​

Choose which table you want to import data into (for example: Projects, Clients, Vendors).

  • Some imports may be pre-scoped to a specific table
  • Others allow you to select the table manually

The available columns and options update automatically when the table changes.

Step 2: Upload a CSV File​

Click Choose CSV and select a .csv file from your computer.

Requirements:

  • The file must include a header row
  • Each column should represent a single field
  • Rows represent individual records

Once uploaded, the system reads the file and prepares it for mapping.

Step 3: Map Columns​

Each column in your CSV must be mapped to a column in the table.

  • CSV columns appear on the left
  • Table columns appear on the right
  • You can skip columns you don’t want to import
  • Matching names are auto-suggested when possible

Required Columns​

Some table fields are required. These are automatically detected from the database schema.

  • Required fields are marked with a * in the column selector
  • You must map all required fields before the import can run
  • If a required field is missing, the import will be blocked with a clear message

This prevents incomplete or invalid records from being created.

Column Type Hints​

Each table column includes a human-friendly type hint to help with mapping, for example:

  • Text – names, descriptions, notes
  • Number – numeric values, costs, quantities
  • Date – calendar dates
  • Date & time – timestamps
  • Yes / No – boolean fields

These hints are derived automatically from the database and help prevent formatting errors.

Only mapped columns will be imported.

Step 4: Choose a Key Column​

The Key Column tells the system how to recognize the same record again.

Think of it as the field that answers this question for every row in your CSV:

“Does this row already exist in the system, or is it brand new?”

Why the Key Column Matters​

When importing data, the system has no way to guess whether a row should:

  • update an existing record, or
  • create a new one

The key column is how you give it that instruction.

For each row in your CSV:

  • If the key value matches an existing record, that record is updated
  • If the key value does not match anything, a new record is created

Without a reliable key column, the system cannot safely update data.

Common Key Column Choices​

id (Recommended when available)

  • The most reliable option
  • Guaranteed to be unique
  • Best choice when updating records that already exist in the system

Email, Name, or Other Identifiers

  • Useful when importing data from another system
  • Must be unique and consistent
  • Risky if values change or contain duplicates

Examples:

  • Email addresses that may change
  • Names that are not unique
  • Project numbers that are inconsistently formatted

What Happens If You Choose the Wrong Key​

Choosing an unreliable key can cause:

  • Duplicate records
  • Overwriting the wrong record
  • Updates not applying when expected

For example:

  • Using name when two clients share the same name
  • Using email when some rows have missing or outdated emails

When to Use Each Import Mode​

The key column works together with the conflict policy:

  • Upsert
    Uses the key column to update existing records or create new ones

  • Insert Only
    Ignores existing records and only creates new ones

  • Update Only
    Updates existing records and skips rows that don’t match the key

Best Practices​

  • Use id whenever possible
  • Only use non-ID keys if you are confident they are unique
  • Be consistent — the same value must always refer to the same record
  • If unsure, start with a small test import

In short:
The key column is how the system knows what to update and what to create.

Step 5: Select a Conflict Policy​

Choose how the system handles existing data:

Upsert (Insert + Update)​

  • Updates records that already exist
  • Creates new records when no match is found
  • Best option for most imports

Insert Only​

  • Creates new records only
  • Skips rows that match existing data

Update Only​

  • Updates existing records only
  • Skips rows that don’t match anything

Step 6: Review the Preview​

Before importing, you’ll see a preview of the first few rows.

Use this to:

  • Confirm column mappings
  • Check formatting
  • Catch obvious issues early

If something looks wrong, you can go back and adjust settings.

Step 7: Confirm the Import​

When you click Import, a confirmation screen shows:

  • Target table
  • File name
  • Conflict policy
  • Number of rows to be created vs updated

Nothing is changed until you confirm.

Data Formatting & Validation​

During import, the system automatically validates data based on column types and constraints:

  • Required fields must be present
  • Numbers, dates, and booleans are validated
  • Invalid rows are rejected with clear error messages

If an import fails, you’ll see an explanation of what needs to be corrected.

Relationships & Lookups​

For fields linked to other tables:

  • The system attempts to match values by ID or display name
  • Matching is case-insensitive
  • If a match is found, the relationship is preserved
  • If no match is found, the row may be rejected

This ensures relationships remain valid and consistent.

After the Import​

Once the import completes:

  • Records appear immediately in tables
  • Widgets refresh automatically
  • Activity logs reflect created or updated records

If any rows fail, the import will report which rows need attention.

Tips for Best Results​

  • Export existing data first to use as a template
  • Start with small test imports
  • Pay attention to required fields
  • Use the preview to verify mappings and formats
  • Avoid importing duplicate or partially cleaned data

Good to Know​

  • Imports can create or update many records at once
  • Changes cannot be undone automatically
  • Large imports may take a few moments to complete
  • Access to CSV import may depend on permissions

Summary​

CSV Import is a powerful tool for managing data at scale. When used carefully, it can save hours of manual work while keeping your data structured, consistent, and accurate.

Think of it as a spreadsheet with rules and safeguards — fast, flexible, and reliable.