FlowMattic Tables CSV Import Guide

Overview

The CSV Import feature in FlowMattic Tables allows you to bulk import data from CSV files into your database tables. This powerful feature supports intelligent column mapping, batch processing for large files, and provides a preview before importing to ensure data accuracy.

Prerequisites

• Access Requirements: Administrator privileges in FlowMattic
• File Format: CSV file with UTF-8 encoding
• File Size: No strict limit (large files are processed in batches)
• Browser Requirements: Modern browser with JavaScript enabled
• Table Setup: Existing table with columns defined

What You Can Do

• 🎯 Automatic Column Matching: The system figures out which CSV columns go with which table columns
• 📁 Easy File Upload: Just drag and drop your CSV file or click to browse
• 👀 Preview Before Import: See exactly how your data will look before committing
• ⚡ Handle Large Files: Import thousands of rows without browser crashes
• 🔄 Watch Progress Live: See your data being added to the table as it imports
• 📝 Smart Header Detection: Automatically skips header rows in your CSV
• ✨ Clear Visual Feedback: Progress bars and indicators show you what’s happening

Step-by-Step Import Process

Step 1: Access the Import Feature

1. Navigate to your FlowMattic table
2. Locate the Import CSV button in the top toolbar (green button with upload icon)
3. Click to open the import modal

Step 2: Upload Your CSV File

You have two options for uploading your CSV file:

Option A: Drag and Drop

1. Drag your CSV file from your computer
2. Drop it onto the designated upload area
3. The file will automatically begin processing

Option B: Browse and Select

1. Click the Browse Files button
2. Navigate to your CSV file location
3. Select the file and click Open

What happens after upload:

• File is validated for CSV format
• Headers are extracted automatically
• File size and row count are displayed
• Progress to the column mapping step

Step 3: Map CSV Columns to Table Columns

This is the most important step where you define how your CSV data maps to your table structure.

Understanding the Mapping Interface

• Left side: Shows your CSV column names with sample data
• Arrow (→): Visual indicator of mapping direction
• Right side: Dropdown to select corresponding table column

Auto-Mapping Feature

The system automatically attempts to match columns based on:

1. Exact matches: “customer_id” → “customer_id”
2. Similar names: “email_address” → “email”
3. Normalized matches: “First-Name” → “first_name”

Manual Mapping Adjustments

1. Review each auto-mapped column
2. Click the dropdown to change mapping if needed
3. Select “Skip this column” for CSV columns you don’t want to import

Important Mapping Rules

• Each table column can only be mapped to one CSV column
• Required table columns must be mapped
• Unmapped CSV columns will be skipped
• Unmapped table columns will be left empty (or use default values)

Step 4: Configure Import Options

Skip Header Row Option

• ✅ Checked (Default): First row is treated as headers and not imported
• ⬜ Unchecked: First row is imported as data

When to uncheck:

• Your CSV file doesn’t have headers
• Headers were already removed
• First row contains actual data

Step 5: Preview Your Import

Before committing to the import, review the preview to ensure data accuracy.

What to Check in Preview:

1. Data Alignment: Ensure data appears in correct columns
2. Data Types: Verify numbers, dates, and text are properly formatted
3. Special Characters: Check that special characters display correctly
4. Empty Fields: Confirm how empty CSV fields are handled

Preview Table Features:

• Shows first 5 rows of data to be imported
• Headers display in human-readable format
• Empty cells are clearly indicated
• Data is formatted as it will appear in the table

Step 6: Execute the Import

Once you’re satisfied with the preview:

1. Click the Import Data button
2. The import process begins with a progress indicator
3. DO NOT close the browser window during import

Import Progress Information:

• Progress Bar: Shows overall completion percentage
• Batch Counter: Displays current batch (e.g., “Processing batch 3 of 10”)
• Row Counter: Shows rows processed (e.g., “150 of 500 rows imported”)
• Real-time Updates: Table refreshes automatically every 5 batches to show imported data
• Time Estimate: Approximate time remaining for large imports

Step 7: Import Completion

Upon successful import:

• ✅ Success message displays with total rows imported
• Table shows imported data in real-time during the process
• Final refresh ensures all data is visible
• Import modal can be safely closed
• Any errors are reported with specific row numbers

Data Formatting Guidelines

CSV File Requirements

id,customer_name,email,registration_date,status
1,"John Doe",[email protected],2025-01-15,active
2,"Jane Smith",[email protected],2025-01-16,pending

Supported Data Types

Special Characters Handling

• Commas: Enclose field in double quotes: "Smith, John"
• Quotes: Escape with double quotes: "He said ""Hello"""
• Newlines: Enclose field in quotes: "Line 1\nLine 2"
• Unicode: Ensure file is UTF-8 encoded

Advanced Features

Importing Large Files

Don’t worry about large CSV files - the system handles them automatically:

• Automatic Processing: Large files are broken into smaller chunks and processed piece by piece
• No Browser Crashes: Your browser won’t freeze or crash even with huge files
• Progress Updates: You’ll see your table update regularly as chunks are processed
• Error Protection: If something goes wrong with one chunk, the previously imported data is safe
• Sit Back and Relax: Everything happens automatically - you just need to keep your browser open

Watching Your Import Progress

As your CSV file is being imported, you can actually watch your data appear in the table in real-time! Here’s what you’ll see:

What Happens During Import

• Your table updates automatically: Every few seconds during the import, your table will refresh to show the newly added records
• Visual indicator: When the table is refreshing, you’ll see a small “Refreshing Table” badge appear next to the import title with a spinning icon
• No interruption: The import continues normally while you can see the progress in your actual table

Why This is Helpful

• Peace of mind: You can see that your data is actually being imported correctly
• Catch issues early: If something looks wrong with your data, you’ll notice it during the import rather than at the end
• Track progress: Watch as your table grows with each batch of imported records
• Stay engaged: Instead of waiting blindly, you can see exactly what’s happening

This means you don’t have to wait until the very end of the import to see if everything worked correctly!

How Smart Column Matching Works

The system automatically tries to match your CSV columns to your table columns by looking for similarities:

1. Perfect matches first: If your CSV has a column called “email” and your table has an “email” column, they’ll be matched automatically
2. Similar names: Columns like “customer_name” in your CSV might match to “Customer Name” in your table
3. Partial matches: A CSV column “first_name” could match to a table column called “name”
4. Flexible formatting: The system ignores differences in spaces, hyphens, and underscores

This saves you time by doing most of the column matching work automatically, but you can always change the matches manually if needed.

Common Issues and Solutions

Issue: “Invalid CSV Format” Error

Cause: File is not properly formatted as CSV
Solution:

• Ensure file has .csv extension
• Save Excel files as CSV (not XLS/XLSX)
• Check for proper comma separation

Issue: Data Appears in Wrong Columns

Cause: Incorrect column mapping
Solution:

• Return to mapping step
• Manually adjust column assignments
• Verify sample data in mapping interface

Issue: Special Characters Display Incorrectly

Cause: Encoding issues
Solution:

• Save CSV file with UTF-8 encoding
• Use text editor to verify encoding
• Remove or replace problematic characters

Issue: Import Stops or Fails

Cause: Network issues or browser timeout
Solution:

• Check internet connection
• Don’t close browser during import
• For very large files, split into smaller CSVs

Issue: Duplicate Column Mapping

Cause: Multiple CSV columns mapping to same table column
Solution:

• System prevents this automatically in latest version
• Each table column can only be mapped once
• Review and adjust mappings manually if needed

Best Practices

Before Importing

1. Backup Your Data: Always backup existing table data
2. Clean Your CSV: Remove unnecessary columns and rows
3. Validate Format: Open in text editor to verify structure
4. Test Small: Try with a few rows first

During Import

1. Stay on Page: Don’t navigate away during import
2. Monitor Progress: Watch progress bar and batch counter
3. Observe Real-time Updates: Watch imported data appear in table
4. Watch for Refresh Badge: Notice when table is updating automatically
5. Check for Errors: Monitor for any error messages or failed batches

After Import

1. Verify Data: Check a sample of imported records
2. Check Totals: Confirm row count matches expectations
3. Test Functionality: Ensure imported data works with your workflows
4. Document Import: Note date, file, and any issues

Performance Tips

Optimizing Large Imports

• Split Large Files: Divide files over 10,000 rows
• Remove Unused Columns: Import only necessary data
• Clean Data First: Fix formatting issues before import
• Use Off-Peak Hours: Import during low-traffic periods

File Preparation Checklist

• [ ] CSV saved in UTF-8 encoding
• [ ] Headers in first row (if applicable)
• [ ] No empty rows in middle of data
• [ ] Special characters properly escaped
• [ ] Date formats consistent
• [ ] Numeric fields don’t contain text

Security Considerations

• Files are processed server-side securely
• No data is stored in browser cache
• Temporary files are deleted after import
• All data is sanitized before database insertion
• User permissions are validated

Limitations

• File Types: Only CSV files supported (not Excel, JSON, XML)
• Rollback: No automatic undo after successful import
• Concurrent Imports: Only one import at a time per table
• Batch Size: Fixed at 50 rows per batch for optimal performance
• Browser Dependency: Requires keeping browser tab open during import

Troubleshooting Checklist

If your import isn’t working as expected:

1. ✓ Is the file in CSV format?
2. ✓ Are all required table columns mapped?
3. ✓ Is the browser window staying open?
4. ✓ Is the internet connection stable?
5. ✓ Are special characters properly escaped?
6. ✓ Is the file encoding UTF-8?
7. ✓ Are date formats consistent?
8. ✓ Have you checked the preview?

Getting Help

If you encounter issues not covered in this guide:

1. Check the FlowMattic documentation
2. Review the FAQ section in the Help modal
3. Contact FlowMattic support with:
   • Table name and structure
   • Sample of your CSV file
   • Error messages received
   • Browser and version used

Last updated: 9 September, 2025
FlowMattic Version: 5.3.0+