WayCool
WayCool
Docs
  • Docs
  • Changelog
  • Feature requests
  • Support portal
    • Import Your Data
    • Fix Import Issues and Re-Run Rows
    • Prepare for a Data Migration
    • Migrating Data Into CoolFocus
    • Importer Best Practices
    • Prepare Your Import File
    • Importing Contacts and Donors
    • Importing donors and contributions with source IDs

Importer Best Practices

Best practices for sample imports, source IDs, dependency order, mapping templates, lookup cleanup, and update imports.

Importer Best Practices

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.

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.

Use Mapping Templates

Save a mapping template after you review a good mapping. Templates are helpful 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.

Recommended File Habits

Do Avoid
Use clear column headers Using vague headers like Field1
Keep source IDs Deleting legacy IDs after the first import
Use one record per row Merged rows, subtotal rows, or notes inside the table
Standardize lookup values Creating many nearly duplicate lookup values
Run a sample import first Uploading a full migration file as the first test
Save mapping templates Rebuilding the same mapping by hand every time

Related Articles

  • Migrating Data overview
  • Prepare for a data migration
  • Import your data
PrevMigrating Data Into CoolFocus
NextPrepare Your Import File
Was this helpful?