Use the Importer from the list where the records belong. For example, to import donors, open the donor list. To import client records, open the client list. Import appears only where importing is enabled for that record type and your user role.
What this article is: the step-by-step import wizard (upload → map → match → preview → run → review). For the section overview, see Migrating Data Into CoolFocus. For planning and file setup first, see Prepare for a Data Migration and Prepare Your Import File.
1. Open the record list you want to import into.
2. Choose Actions.
3. Choose Import.
4. Select Create new records or Update existing records.
5. Enter the Source System if this data came from another system.
6. Upload a CSV, XLSX, or XLS file.
7. Choose Continue to Column Mapping.
The Map columns step matches columns from your file to fields in CoolFocus.
CoolFocus suggests mappings when it can recognize a column. Review every suggested mapping before continuing.
You can:
• Choose Don't import for columns you do not need
• Apply cleansing rules such as trimming spaces, changing case, keeping digits only, or treating empty values as blank
• Preview sample values from the file
• See required field progress
• Save a mapping as a template for future files
• Load a saved template when the same source file format is used again
Choose Continue to Matching when all required fields are mapped.
For contribution and recurring contribution imports, you must map a way to link each gift to a donor (Donor or Donor Source Id). Details: Importing donors and contributions with source IDs.
The Match lookups step checks values from your file against lookup values and related records in CoolFocus.
• If every value matches, review the summary and continue.
• If some values need attention, map them to the right existing value. When allowed for that lookup type and your permissions, you can also create missing values one at a time or use Create all.
These mappings are saved for future imports, so review them carefully.
The Preview step validates rows before the import runs. Use it to catch problems while they are still easy to fix.
While the preview is generating, a progress indicator shows what CoolFocus is doing (reading the spreadsheet, preparing validation rules, validating rows, checking source matches). For larger files, it shows a row count and percent complete. It refreshes automatically as validation runs in the background.
Once the preview finishes, you can:
• See counts for total, valid, invalid, edited, matched existing, and skipped rows
• Search, sort, and filter rows
• Double-click a cell to edit a value
• Expand a flagged row to see validation errors
• Skip a row that should not be imported
• Download issues as a CSV
If every row is valid, choose Start Import.
If some rows are invalid in a create import, you can still import the valid rows after confirming that invalid rows will be skipped. Download the issues first so those rows can be corrected and imported later.
For update imports, the preview shows how many records matched. Type the requested row count to confirm before choosing Start Update.
The import runs in the background. The progress page shows:
• Processed rows
• Successful rows
• Failed rows
• Current status
• Start and completion time
Large files are processed in chunks. Progress advances as each chunk finishes. If processing is interrupted, CoolFocus resumes from the next row when processing starts again. You also see progress and controls in background notifications while the import is queued or running.
To stop an import that is queued or actively processing, choose Stop Import and confirm. Stopping prevents any new chunks from starting. Rows that were already processed remain. This action cannot be undone. Once you confirm, the status changes to Cancelled.
You do not need to stay on the progress page. You receive a completion notification when the import finishes.
• Large imports are processed in batches behind the scenes. You can close the page and return later.
• For very large files, processing can take hours. Progress updates continue as each batch finishes.
• If a batch runs out of time, CoolFocus resumes the import automatically. No action is required. The next batch starts at the next unprocessed row after the last processed or failed row.
• Failed rows are not retried automatically during a resume. Use Re-run Failed Rows after fixing the cause.
• You can stop an import at any time. Processed rows remain, and you can handle failed rows later from import history.
When the import completes, review the completion summary.
If rows failed, download the error report. You can also open Import History to review details, mappings, imported rows, skipped rows, and errors. Next steps for cleanup: Fix Import Issues and Re-Run Rows.
• Migrating Data Into CoolFocus
• Prepare for a Data Migration
• Prepare Your Import File
• Fix Import Issues and Re-Run Rows
• Importer Best Practices
• Importing donors and contributions with source IDs
Best practices for sample imports, source IDs, dependency order, mapping templates, lookup cleanup, and update imports.
How to map donor and gift IDs when importing donors first, then contributions or recurring gifts, using Source System and Donor Source Id.
Use Actions → Import from the Time Sheets grid to add staff and volunteer hours from a CSV or Excel file.
Use preview, issue downloads, skipped rows, import history, error reports, and re-run options to finish cleanup.
