Legacy Order Import - Quick Reference Guide

Prerequisites

Import Customers First
```
bin/rails legacy:import_customers
```
This creates companies with "Legacy ID: XXX" in notes for mapping.
Verify Vendors & Products Exist
- Ensure your current system has vendors set up
- Ensure products are created
- The import will map by name (case-insensitive)

Available Commands

1. Test Legacy Database Connection

bin/rails legacy:test

Shows if you can connect to the legacy MySQL database.

2. View Legacy Data Statistics

bin/rails legacy:stats

Shows order counts, status breakdown, top vendors, recent orders.

3. Preview Order Import

# Preview all orders from last 2 years
bin/rails legacy:preview_order_import

# Preview specific date range
bin/rails legacy:preview_order_import[2024-01-01,2025-12-31]

This shows:

How many orders would be imported
Breakdown by status, vendor, product
Revenue totals
Mapping coverage (vendors/products/customers)

4. Dry Run Import

# Test import without saving (default is dry run)
bin/rails legacy:import_orders[2024-01-01,2025-12-31]

# Or explicitly
bin/rails legacy:import_orders[2024-01-01,2025-12-31,true]

Shows exactly what would happen without actually importing.

5. Actual Import

# CAUTION: This actually imports data!
bin/rails legacy:import_orders[2024-01-01,2025-12-31,false]

6. Generate Uninvoiced Orders Report

bin/rails legacy:uninvoiced_orders_report

Creates a CSV file with all imported orders that need invoicing.

Import Process Flow

1. Connect to Legacy DB
   ↓
2. Map Vendors (by name)
   ↓
3. Map Products (by name)
   ↓
4. Map Customers (by legacy ID in notes)
   ↓
5. For Each Order:
   - Check if already imported (skip if yes)
   - Map status (delivered → active, etc.)
   - Map payment method (cc → credit_card, etc.)
   - Calculate rental days from dates
   - Create company/contact if needed
   - Import order with all fields
   - Track with legacy_order_id
   ↓
6. Generate Summary Report

What Gets Imported

Order Fields Mapped:

✅ Order number (kept from legacy)
✅ Customer (company + contact)
✅ Vendor & Product
✅ Delivery/pickup dates & address
✅ Pricing (base, fees, totals)
✅ Vendor costs (for profit tracking)
✅ Payment method & billing address
✅ Notes (customer & internal)
✅ Status (with mapping)

Tracking Fields Added:

legacy_order_id - Original order ID
imported_at - When imported
import_notes - Import details (original product name, vendor, PO#)

After Import

Review Imported Orders

# In Rails console
bin/rails console

# See all imported orders
Order.where.not(legacy_order_id: nil).count

# See uninvoiced imported orders
Order.where.not(legacy_order_id: nil).where(invoice_id: nil).count

# Find a specific legacy order
Order.find_by(legacy_order_id: 12345)

Generate Invoices

Run uninvoiced report:

bin/rails legacy:uninvoiced_orders_report

Review the CSV file
Use the billing run system to create invoices:
- Go to Admin → Billing Runs
- Click "New Billing Run"
- Select companies with uninvoiced orders
- Generate draft invoices
- Review and send

Rollback

If something goes wrong:

# In Rails console
bin/rails console

# Delete ALL imported orders
Order.where.not(legacy_order_id: nil).delete_all

# Delete orders imported after a certain time
Order.where.not(legacy_order_id: nil)
     .where("imported_at > ?", 1.hour.ago)
     .delete_all

# Then re-run import with corrections

Troubleshooting

"Can't connect to server on '127.0.0.1'"

Legacy database requires SSH tunnel or VPN
Check your database_legacy.yml connection settings
Verify you have access to the remote MySQL server

"Vendor/Product not found"

The import maps by name (case-insensitive)
If no match found, uses first vendor/product as fallback
Check import_notes field to see original vendor/product names
Manually update after import if needed

"Customer not found"

Run legacy:import_customers first
Or the import will auto-create companies with basic info
Auto-created companies have note: "Auto-created during order import"

"Already imported" messages

Orders with matching legacy_order_id are skipped
This allows incremental imports
Re-import is safe and idempotent

Best Practices

Start Small
- Import 3-6 months first
- Verify data quality
- Then expand date range

Always Use Dry Run First

bin/rails legacy:import_orders[2024-01-01,2024-03-31]
# Review output, then:
bin/rails legacy:import_orders[2024-01-01,2024-03-31,false]

Import in Batches
- Q1: Jan-Mar
- Q2: Apr-Jun
- Q3: Jul-Sep
- Q4: Oct-Dec
Focus on Uninvoiced First
- Import only "completed" and "active" statuses
- Generate invoices immediately
- Then import historical for record-keeping
Verify After Import
- Check order counts match
- Verify customer relationships
- Compare totals
- Review uninvoiced report

Data Mapping Reference

Status Mapping

Legacy	New	Invoiceable?
pending	pending	No
confirmed	confirmed	No
delivered	active	No
active	active	Yes
completed	completed	Yes
cancelled	cancelled	No

Payment Method Mapping

Legacy	New
cc, credit_card	credit_card
po, purchase_order	purchase_order
cash	purchase_order
check	purchase_order

Support

For issues or questions:

Check import_notes field on orders
Review error messages in import output
Use Rails console to inspect data
Check docs/legacy_order_import.md for detailed strategy

Example Workflow

# 1. Test connection
bin/rails legacy:test

# 2. Import customers (if not done)
bin/rails legacy:import_customers

# 3. Preview what would be imported
bin/rails legacy:preview_order_import[2024-01-01,2024-12-31]

# 4. Dry run to see details
bin/rails legacy:import_orders[2024-01-01,2024-12-31]

# 5. Review output, then actually import
bin/rails legacy:import_orders[2024-01-01,2024-12-31,false]

# 6. Generate uninvoiced report
bin/rails legacy:uninvoiced_orders_report

# 7. Open the CSV and review
# 8. Create invoices via billing runs in admin UI