Use these practices to keep migrations predictable and easy to review.
Start small
Run a small sample before importing a full file. A good sample includes:
• At least one complete row
• A row with optional fields blank
• A row for each important lookup value
• A row that should match an existing record
• A row that should fail validation, if you want to confirm the error path
Once the sample looks right, use the same mapping template for the full import.
Keep source IDs
Do not remove IDs from the old system. Source IDs help CoolFocus connect related imports when that record type supports source identity matching.
For a donor migration, keep the donor or account ID. For a contribution migration, keep both the donor reference and the donation or transaction ID. For recurring contribution imports, keep the recurring donation or schedule ID. Use the same Source System name for files from the same source.
More detail: Importing donors and contributions with source IDs.
Import in dependency order
Import parent records before child records. For example:
1. Import contacts or donors.
2. Import lookup values or map them during import.
3. Import gifts, activities, enrollments, or other records that depend on those contacts.
This makes matching clearer and reduces failed rows. Full planning checklist: Prepare for a Data Migration.
Use mapping templates
Save a mapping template after you review a good mapping. Templates help when:
• You receive the same spreadsheet format every month
• You are splitting a large migration into several files
• You want another team member to follow the same mapping
Still review the mapping each time. A source system export can change columns without warning.
Clean lookup values before uploading
Lookups are easier to map when values are consistent.
Before uploading, standardize values such as:
• General Fund vs. General
• Volunteer vs. Volunteers
• Food Pantry vs. Pantry
• Active vs. Current
If CoolFocus shows unmatched lookup values, map them intentionally. Do not create new values unless your team wants those values available going forward. Creating new lookup values may require admin access.
Treat update imports as high impact
Update imports change existing records. Use them only when you are confident the file identifies the correct records.
Before running an update import:
• Confirm the file has Id or DistinctImportId
• Confirm the Source System is correct
• Review the matched and unmatched row counts
• Type the confirmation only after the preview matches your expectation
• Keep the original file available in import history
Review results before moving on
After each import:
• Compare the expected row count with imported, skipped, and failed counts
• Open a few imported records and verify key fields
• Download the error report if any rows failed
• Re-run failed rows only after the cause is fixed
• Rename the import if the default name is not descriptive enough
Cleanup path: Fix Import Issues and Re-Run Rows.
Recommended file habits
• Do use clear column headers — avoid vague headers like Field1
• Do keep source IDs — avoid deleting legacy IDs after the first import
• Do use one record per row — avoid merged rows, subtotal rows, or notes inside the table
• Do standardize lookup values — avoid creating many nearly duplicate lookup values
• Do run a sample import first — avoid uploading a full migration file as the first test
• Do save mapping templates — avoid rebuilding the same mapping by hand every time
File formatting detail: Prepare Your Import File.