Data Import

Taskr supports bulk data import from CSV and Excel files, enabling easy migration from legacy systems or one-time data uploads.

Supported Import Types

Customers

Import customer records with contact details and billing information

Assets

Import equipment and asset inventory with specifications

Invoices

Import historical invoices with line items and payment status

Locations

Import service locations with addresses and contact info

Vendors

Import supplier and vendor records

Employees

Import team member records for onboarding

Import Flow

Import Process

Upload File

User uploads a CSV or Excel file. Supported formats:

.csv - Comma-separated values
.xlsx - Excel 2007+ format
.xls - Legacy Excel format

// apps/workbooks-dashboard/src/components/modals/csv-import/generic-csv-import-modal.tsx

const handleFileUpload = async (file: File) => {
  const extension = file.name.split(".").pop()?.toLowerCase();
  
  if (extension === "csv") {
    return parseCSV(file);
  } else if (["xlsx", "xls"].includes(extension!)) {
    return parseExcel(file);
  }
  
  throw new Error("Unsupported file format");
};

Column Detection

Automatic detection of column headers and data types:

const detectColumns = (headers: string[], sampleRows: string[][]) => {
  return headers.map((header, index) => ({
    name: header,
    index,
    detectedType: inferType(sampleRows.map(row => row[index])),
    suggestedMapping: fuzzyMatchField(header),
  }));
};

// Type inference
const inferType = (values: string[]): FieldType => {
  if (values.every(isValidEmail)) return "email";
  if (values.every(isValidPhone)) return "phone";
  if (values.every(isValidDate)) return "date";
  if (values.every(isNumeric)) return "number";
  return "text";
};

Field Mapping

User maps source columns to Taskr fields:

// Interactive mapping interface
interface FieldMapping {
  sourceColumn: string;
  targetField: string;
  transform?: "uppercase" | "lowercase" | "trim" | "date";
  required: boolean;
}

// Auto-suggest mappings based on column names
const suggestMapping = (columnName: string): string | null => {
  const normalized = columnName.toLowerCase().replace(/[_\s-]/g, "");
  
  const mappings: Record<string, string[]> = {
    name: ["name", "customername", "fullname", "companyname"],
    email: ["email", "emailaddress", "mail", "primaryemail"],
    phone: ["phone", "phonenumber", "telephone", "mobile"],
    address: ["address", "streetaddress", "addr", "address1"],
  };
  
  for (const [field, patterns] of Object.entries(mappings)) {
    if (patterns.includes(normalized)) return field;
  }
  
  return null;
};

Data Validation

Validate all rows before import:

interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
  validRows: number;
  invalidRows: number;
}

const validateImport = async (
  rows: ImportRow[],
  config: ImportConfig
): Promise<ValidationResult> => {
  const errors: ValidationError[] = [];
  
  for (let i = 0; i < rows.length; i++) {
    const row = rows[i];
    
    // Required fields
    for (const field of config.requiredFields) {
      if (!row[field]) {
        errors.push({
          row: i + 1,
          field,
          message: `${field} is required`,
        });
      }
    }
    
    // Email format
    if (row.email && !isValidEmail(row.email)) {
      errors.push({
        row: i + 1,
        field: "email",
        message: "Invalid email format",
      });
    }
    
    // Duplicate detection
    const duplicate = await checkDuplicate(row);
    if (duplicate) {
      errors.push({
        row: i + 1,
        field: "name",
        message: `Duplicate of existing record: ${duplicate.name}`,
      });
    }
  }
  
  return {
    valid: errors.length === 0,
    errors,
    warnings: [],
    validRows: rows.length - errors.length,
    invalidRows: errors.length,
  };
};

Background Import

Large imports run as background jobs with progress tracking:

// apps/workbooks-dashboard/src/actions/csv-import/import-customers.ts

export async function importCustomers(
  teamId: string,
  rows: CustomerImportRow[],
  options: ImportOptions
): Promise<ImportResult> {
  const results = {
    created: 0,
    updated: 0,
    skipped: 0,
    errors: [] as ImportError[],
  };
  
  for (const row of rows) {
    try {
      if (options.updateExisting) {
        const existing = await findExistingCustomer(row);
        if (existing) {
          await updateCustomer(existing.id, row);
          results.updated++;
          continue;
        }
      }
      
      await createCustomer(teamId, row);
      results.created++;
    } catch (error) {
      results.errors.push({
        row: row._rowNumber,
        error: error.message,
      });
    }
  }
  
  return results;
}

Entity-Specific Configurations

Customers
Assets
Invoices
Locations

Required Fields

name - Customer name or company name

Optional Fields

Field	Type	Description
`email`	Email	Primary contact email
`phone`	Phone	Primary phone number
`address`	Text	Street address
`city`	Text	City name
`state`	Text	State/province
`postalCode`	Text	ZIP/postal code
`country`	Text	Country (ISO code or name)
`notes`	Text	Additional notes
`accountNumber`	Text	External account number
`paymentTerms`	Number	Payment terms in days

Example CSV

name,email,phone,address,city,state,postalCode
"Acme Corp","[email protected]","555-1234","123 Main St","Austin","TX","78701"
"Beta Inc","[email protected]","555-5678","456 Oak Ave","Dallas","TX","75201"

Required Fields

name - Asset name or identifier
assetType - Type of asset (must match existing asset types)

Optional Fields

Field	Type	Description
`serialNumber`	Text	Manufacturer serial number
`manufacturer`	Text	Manufacturer name
`model`	Text	Model number
`installDate`	Date	Installation date
`warrantyExpiry`	Date	Warranty expiration
`location`	Text	Location name (must exist)
`customer`	Text	Customer name (must exist)
`notes`	Text	Additional notes

Date Handling

// apps/workbooks-dashboard/src/actions/csv-import/import-assets.ts

// Supports multiple date formats
const parseExcelDate = (value: string | number): Date => {
  // Excel serial date (number of days since 1900-01-01)
  if (typeof value === "number") {
    return new Date((value - 25569) * 86400 * 1000);
  }
  
  // ISO format
  if (/^\d{4}-\d{2}-\d{2}/.test(value)) {
    return new Date(value);
  }
  
  // US format (MM/DD/YYYY)
  if (/^\d{1,2}\/\d{1,2}\/\d{4}/.test(value)) {
    const [month, day, year] = value.split("/");
    return new Date(+year, +month - 1, +day);
  }
  
  throw new Error(`Invalid date format: ${value}`);
};

Required Fields

invoiceNumber - Unique invoice identifier
customerName or customerId - Customer reference
date - Invoice date
total - Total amount

Optional Fields

Field	Type	Description
`dueDate`	Date	Payment due date
`status`	Enum	paid, unpaid, overdue
`currency`	Text	Currency code (USD, EUR, etc.)
`lineItems`	JSON	Array of line items
`notes`	Text	Invoice notes
`paidDate`	Date	Date payment received
`paidAmount`	Number	Amount paid

Currency Handling

// apps/workbooks-dashboard/src/actions/csv-import/import-invoices.ts

const parseCurrency = (value: string): number => {
  // Remove currency symbols and formatting
  const cleaned = value.replace(/[^0-9.-]/g, "");
  const amount = parseFloat(cleaned);
  
  if (isNaN(amount)) {
    throw new Error(`Invalid currency value: ${value}`);
  }
  
  return amount;
};

Required Fields

name - Location name
customerId or customerName - Parent customer

Optional Fields

Field	Type	Description
`address`	Text	Street address
`city`	Text	City
`state`	Text	State/province
`postalCode`	Text	ZIP/postal code
`country`	Text	Country
`contactName`	Text	Site contact name
`contactPhone`	Text	Site contact phone
`contactEmail`	Email	Site contact email
`locationType`	Enum	commercial, residential, industrial
`latitude`	Number	GPS latitude
`longitude`	Number	GPS longitude

Import Options

Option	Default	Description
`skipDuplicates`	`true`	Skip rows that match existing records
`updateExisting`	`false`	Update records if duplicates found
`skipEmptyRows`	`true`	Ignore completely empty rows
`trimValues`	`true`	Remove leading/trailing whitespace
`batchSize`	`100`	Number of records per batch

Error Handling

Missing Required Fields

Cause: Row is missing a required fieldResolution:

Fix in source file and re-upload
Or mark field as “skip this row” in validation UI

Invalid Email Format

Cause: Email doesn’t match expected formatResolution:

Correct email in source file
Or clear the field to import without email

Duplicate Record

Cause: Record with same key already existsResolution:

Enable “Update existing” to merge records
Or enable “Skip duplicates” to ignore
Or rename record to create new entry

Reference Not Found

Cause: Referenced entity (customer, location) doesn’t existResolution:

Import parent entities first
Or create missing entities manually
Or update reference to existing entity name

Date Parse Error

Cause: Date format not recognizedSupported formats:

ISO: 2025-01-04
US: 01/04/2025 or 1/4/2025
EU: 04/01/2025 (if configured)
Excel serial number

Progress Tracking

For large imports (500+ records), progress is tracked in real-time:

interface ImportProgress {
  total: number;
  processed: number;
  created: number;
  updated: number;
  skipped: number;
  errors: number;
  currentRow: number;
  status: "processing" | "complete" | "failed";
  estimatedTimeRemaining: number;
}

// Real-time updates via WebSocket or polling
const trackProgress = async (importId: string) => {
  return useQuery({
    queryKey: ["import-progress", importId],
    queryFn: () => getImportProgress(importId),
    refetchInterval: 1000, // Poll every second
    enabled: status !== "complete",
  });
};

Import Results

After import completes, users see a summary:

interface ImportResult {
  success: boolean;
  duration: number; // milliseconds
  summary: {
    totalRows: number;
    created: number;
    updated: number;
    skipped: number;
    failed: number;
  };
  errors: Array<{
    row: number;
    field: string;
    value: string;
    message: string;
  }>;
  warnings: Array<{
    row: number;
    field: string;
    message: string;
  }>;
  // Link to view imported records
  viewUrl: string;
}

API Endpoints

Endpoint	Method	Description
`import.uploadFile`	Mutation	Upload and parse file
`import.getColumns`	Query	Get detected columns
`import.validateMapping`	Mutation	Validate field mapping
`import.preview`	Query	Preview mapped data
`import.execute`	Mutation	Start background import
`import.getProgress`	Query	Get import progress
`import.getResult`	Query	Get import results

Best Practices

Always backup your existing data before performing large imports!

Start Small: Test with a few rows before importing entire dataset
Clean Data First: Remove invalid characters and fix formatting in source
Import in Order: Import customers before locations, locations before assets
Use Preview: Always review the preview before confirming import
Check Duplicates: Decide on duplicate handling before starting
Monitor Progress: Watch the progress bar for large imports

Data Migration Wizard

Guided migration from other systems

Accounting Sync

Ongoing sync with QuickBooks/Xero

Developer - Overview

Core Workflows

Billing & Subscriptions

Integrations

Team Management

Onboarding Wizards

Reference

Supported Import Types

Customers

Assets

Invoices

Locations

Vendors

Employees

Import Flow

Import Process

Entity-Specific Configurations

Required Fields

Optional Fields

Example CSV

Required Fields

Optional Fields

Date Handling

Required Fields

Optional Fields

Currency Handling

Required Fields

Optional Fields

Import Options

Error Handling

Progress Tracking

Import Results

API Endpoints

Best Practices

Data Migration Wizard

Accounting Sync

​Supported Import Types

Customers

Assets

Invoices

Locations

Vendors

Employees

​Import Flow

​Import Process

​Entity-Specific Configurations

​Required Fields

​Optional Fields

​Example CSV

​Required Fields

​Optional Fields

​Date Handling

​Required Fields

​Optional Fields

​Currency Handling

​Required Fields

​Optional Fields

​Import Options

​Error Handling

​Progress Tracking

​Import Results

​API Endpoints

​Best Practices

​Related Documentation

Data Migration Wizard

Accounting Sync

Supported Import Types

Import Flow

Import Process

Entity-Specific Configurations

Required Fields

Optional Fields

Example CSV

Required Fields

Optional Fields

Date Handling

Required Fields

Optional Fields

Currency Handling

Required Fields

Optional Fields

Import Options

Error Handling

Progress Tracking

Import Results

API Endpoints

Best Practices

Related Documentation