Data Migration

The Data Migration wizard helps you import existing business data from popular platforms or CSV/Excel files, with intelligent field mapping and validation.

Supported Sources

QuickBooks

Import customers, invoices, items, and vendors via API connection

Xero

Import contacts, invoices, items, and bank transactions via API

ServiceTitan

Import customers, locations, equipment, and job history

CSV/Excel

Upload spreadsheets with flexible field mapping

Migration Flow

Provider-Specific Guides

QuickBooks
Xero
ServiceTitan
CSV/Excel

Connection Steps

Authorize Access

Click “Connect QuickBooks” to open the authorization window. Sign in to your QuickBooks account and grant Taskr access.

Select Company

If you have multiple QuickBooks companies, select which one to import from.

Choose Data

Select which entity types to import:

✅ Customers (recommended)
✅ Items/Services (recommended)
☐ Invoices (optional)
☐ Vendors (optional)
☐ Payments (optional)

Review Mappings

Taskr automatically maps QuickBooks fields. Review and adjust:

QuickBooks Field	Taskr Field
DisplayName	Customer Name
PrimaryEmailAddr	Email
PrimaryPhone	Phone
BillAddr	Billing Address
ShipAddr	Service Address

Import

Click “Start Import” to begin. Large imports run in the background.

What Gets Imported

Entity	Fields Imported
Customers	Name, email, phone, addresses, notes
Items	Name, description, price, type
Invoices	Number, date, line items, status
Vendors	Name, contact info, payment terms

Connection Steps

Authorize Access

Click “Connect Xero” and sign in to your Xero account. Select the organization you want to import from.

Select Tenant

Xero allows multiple organizations. Choose the one to import.

Choose Data

Select entity types:

✅ Contacts (Customers) - recommended
✅ Items - recommended
☐ Invoices (optional)
☐ Bank Transactions (optional)

Review Mappings

Xero Field	Taskr Field
Name	Customer Name
EmailAddress	Email
Phones[0]	Phone
Addresses[0]	Billing Address

Import

Start the import process. Progress is shown in real-time.

Connection Steps

Generate API Key

In ServiceTitan, go to Settings → Integrations → API Access. Generate a new API key for Taskr.

Enter Credentials

Provide your ServiceTitan:

Tenant ID
Client ID
Client Secret

Choose Data

Select what to import:

✅ Customers
✅ Locations
✅ Equipment (→ Assets)
☐ Job History (optional)
☐ Invoices (optional)

Map Equipment Types

Map ServiceTitan equipment types to Taskr asset types:

ServiceTitan	Taskr Asset Type
HVAC Unit	HVAC System
Water Heater	Water Heater
Furnace	Heating System

Import

Begin import with relationship preservation.

Relationship Handling

ServiceTitan data is imported with relationships intact:

Customer → Locations → Equipment

Taskr creates:

Customer → Locations → Assets (with compliance rules)

File Upload

Download Template

Download our CSV template for the entity type you’re importing. Templates include all supported columns with examples.

Prepare Data

Fill in the template with your data. Tips:

First row must be column headers
Use UTF-8 encoding for special characters
Dates in YYYY-MM-DD or MM/DD/YYYY format
Leave optional columns blank if not needed

Upload File

Drag and drop or click to upload your file. Supported: .csv, .xlsx, .xls

Map Columns

Match your columns to Taskr fields. Auto-detection suggests mappings based on column names.

Validate

Review validation results:

✅ Valid rows ready to import
⚠️ Warnings (will import with notes)
❌ Errors (must be fixed)

Import

Confirm and start the import process.

Template Downloads

Entity	Template Link
Customers	customers-template.csv
Locations	locations-template.csv
Assets	assets-template.csv
Invoices	invoices-template.csv

Field Mapping

Smart Detection

Taskr automatically detects and suggests field mappings:

// apps/workbooks-dashboard/src/components/onboarding/data-migration/index.ts

const autoMapFields = (sourceColumns: string[]): FieldMapping[] => {
  const mappings: FieldMapping[] = [];
  
  for (const column of sourceColumns) {
    const normalized = column.toLowerCase().replace(/[\s_-]/g, "");
    
    // Pattern matching for common fields
    if (normalized.includes("email")) {
      mappings.push({ source: column, target: "email", confidence: 0.9 });
    } else if (normalized.includes("phone") || normalized.includes("tel")) {
      mappings.push({ source: column, target: "phone", confidence: 0.85 });
    } else if (normalized.includes("name") && !normalized.includes("company")) {
      mappings.push({ source: column, target: "name", confidence: 0.8 });
    }
    // ... more patterns
  }
  
  return mappings;
};

Manual Override

Users can override any automatic mapping:

interface FieldMapping {
  source: string;      // Source column name
  target: string;      // Taskr field
  transform?: string;  // Optional transformation
  required: boolean;   // Is target field required?
  confidence: number;  // Auto-mapping confidence
}

Data Validation

Validation Rules

Rule	Description	Error Level
Required fields	Name, email (if specified)	Error
Email format	Valid email structure	Error
Phone format	Valid phone number	Warning
Duplicate detection	Matches existing records	Warning
Date format	Parseable date string	Error
Numeric values	Valid numbers for amounts	Error

Handling Duplicates

Options for duplicate handling:

Skip duplicates - Don’t import matching records
Update existing - Merge new data into existing records
Create anyway - Import as new records (may create duplicates)

Progress Tracking

Large imports show real-time progress:

interface ImportProgress {
  status: "preparing" | "importing" | "finalizing" | "complete" | "error";
  totalRecords: number;
  processedRecords: number;
  createdRecords: number;
  updatedRecords: number;
  skippedRecords: number;
  errorRecords: number;
  currentEntity: string;
  estimatedTimeRemaining: number;
  errors: ImportError[];
}

Progress UI

┌─────────────────────────────────────────────────────────────┐
│  Importing Customers                              75% ████░ │
├─────────────────────────────────────────────────────────────┤
│  ✓ 150 created  │  ↻ 23 updated  │  ⊘ 5 skipped  │  ✗ 2 err │
├─────────────────────────────────────────────────────────────┤
│  Processing: ACME Corporation                               │
│  Estimated time remaining: 2 minutes                        │
└─────────────────────────────────────────────────────────────┘

Import Results

After completion, users see a detailed summary:

interface ImportResult {
  success: boolean;
  duration: number;
  summary: {
    customers: { created: 150, updated: 23, skipped: 5, errors: 2 };
    locations: { created: 89, updated: 12, skipped: 0, errors: 0 };
    assets: { created: 234, updated: 0, skipped: 15, errors: 3 };
  };
  errors: Array<{
    entity: string;
    row: number;
    field: string;
    message: string;
    value: string;
  }>;
  nextSteps: string[];
}

Post-Import Actions

Review Imported Data

Navigate to Customers, Assets, or Locations to verify imported data. Use filters to find recently imported records.

Fix Errors

Download error report to see which rows failed. Fix issues in source data and re-import failed rows.

Set Up Compliance

If you imported assets, proceed to compliance setup to configure maintenance schedules and regulatory requirements.

Connect Accounting

For ongoing sync (not just one-time import), connect your accounting system for bidirectional updates.

Best Practices

Always backup your source data before migration. While Taskr doesn’t modify source systems, having a backup ensures you can restart if needed.

Start with a test import - Import a small subset first to verify mappings
Clean source data - Remove duplicates and fix formatting in source
Import in order - Customers first, then locations, then assets
Verify relationships - Check that assets link to correct locations
Review before confirming - Use preview to spot issues early

Troubleshooting

Connection Failed

Cause: OAuth token expired or revokedSolution: Re-authorize the connection from Settings → Integrations

Import Stuck

Cause: Large import processing in backgroundSolution: Wait for completion. Check progress in Settings → Import History

Missing Fields

Cause: Source system doesn’t have required dataSolution: Use CSV import with manual data entry for missing fields

Duplicate Customers

Cause: Same customer imported multiple timesSolution: Use “Update existing” option or merge duplicates after import

API Endpoints

Endpoint	Method	Description
`migration.getSources`	Query	List available import sources
`migration.connect`	Mutation	Connect to external system
`migration.getPreview`	Query	Preview data before import
`migration.start`	Mutation	Begin import process
`migration.getProgress`	Query	Get import progress
`migration.cancel`	Mutation	Cancel in-progress import

Data Import

Detailed CSV/Excel import guide

Accounting Sync

Ongoing QuickBooks/Xero sync

Developer - Overview

Core Workflows

Billing & Subscriptions

Integrations

Team Management

Onboarding Wizards

Reference

Supported Sources

QuickBooks

Xero

ServiceTitan

CSV/Excel

Migration Flow

Provider-Specific Guides

Connection Steps

What Gets Imported

Connection Steps

Connection Steps

Relationship Handling

File Upload

Template Downloads

Field Mapping

Smart Detection

Manual Override

Data Validation

Validation Rules

Handling Duplicates

Progress Tracking

Progress UI

Import Results

Post-Import Actions

Best Practices

Troubleshooting

API Endpoints

Data Import

Accounting Sync

​Supported Sources

QuickBooks

Xero

ServiceTitan

CSV/Excel

​Migration Flow

​Provider-Specific Guides

​Connection Steps

​What Gets Imported

​Connection Steps

​Connection Steps

​Relationship Handling

​File Upload

​Template Downloads

​Field Mapping

​Smart Detection

​Manual Override

​Data Validation

​Validation Rules

​Handling Duplicates

​Progress Tracking

​Progress UI

​Import Results

​Post-Import Actions

​Best Practices

​Troubleshooting

​API Endpoints

​Related Documentation

Data Import

Accounting Sync

Supported Sources

Migration Flow

Provider-Specific Guides

Connection Steps

What Gets Imported

Connection Steps

Connection Steps

Relationship Handling

File Upload

Template Downloads

Field Mapping

Smart Detection

Manual Override

Data Validation

Validation Rules

Handling Duplicates

Progress Tracking

Progress UI

Import Results

Post-Import Actions

Best Practices

Troubleshooting

API Endpoints

Related Documentation