The importer lets you bring existing contact and donor records into CoolFocus from a CSV file. Each row in your file is mapped to a field in CoolFocus and processed as its own record.
1. Upload your CSV file and map each source column to a CoolFocus field.
2. CoolFocus processes the file in background chunks. If processing is inerrupted, it resumes from the last ckground completed row thunk next time it runs.
3. When the import finishes, each row is marked as either Processed or Failed.
4. The overall import status is set to Completed, Partially Completed, or Failed depending on the outcome.
Status | Meaning |
|---|---|
Pending | The file has been uploaded and is waiting to start. |
Processing | The import is actively running. |
Completed | All rows were processed successfully. |
Partially Completed | Some rows succeeded and some failed. Successful rows are saved; failed rows can be reviewed. |
Failed | No rows were committed. Review the error details and correct your file before retrying. |
Each row is processed independently. If a row has a problem, only that row is marked Failed and given an error message. The rest of the batch is still saved.
Common reasons a row fails:
• A field value is too long for the destination column. For example, a phone number longer than 25 characters will be rejected, and the error message will identify which field and the maximum allowed length.
• A required relationship or lookup value could not be resolved.
• A database constraint was violated, such as a duplicate unique value.
When a row fails, its error message is shown in the import row detail so you can correct and re-import only the affected records.
Contact and donor imports can map two optional columns to place imported people into households:
• Household Name: the name of the household the person belongs to (aliases recognized during column mapping include household, household_name, and householdname).
• Household Distinct Import Id: an identifier for the household from your source system (aliases include household_distinct_import_id, household_distinct_id, and household import id).
When a row includes either column, CoolFocus looks for a matching household and links the imported person to it:
1. If Household Distinct Import Id is present, CoolFocus first looks for an existing household with that same distinct import ID.
2. If no match is found by ID, or no ID was given, CoolFocus looks for an existing household with a matching Household Name. If that household did not already have a distinct import ID, the one from this row is saved to it, so later rows can match it by ID as well.
3. If no existing household matches, CoolFocus creates a new household record using the household name, or the distinct import ID if no name was given.
Donor imports only match or create households that are flagged as donor households. Contact imports only match or create non-donor households. This keeps donor households and contact households separate even if they share the same name.
If neither column is mapped or both are blank on a row, the imported person is not linked to any household.
1. Open the import record and filter rows by Failed status.
2. Read the error message on each failed row to understand what needs to be corrected.
3. Fix the values in your source file for just the failed rows.
4. Run a new import with the corrected file.
• Phone numbers: keep phone values at 25 characters or fewer, including any formatting characters such as parentheses, spaces, or hyphens. Long notes or descriptions appended to a phone field (for example, "555-1234 (James Lee/Parent)") should be moved to a notes column instead.
• Column mapping: double-check that each source column is mapped to the correct CoolFocus field before starting the import.
• Test with a small file first: run a 10-20 row sample before importing thousands of records.
Large importss unks are processed in multiple bickgrounterrupted,d chks and marting run for a processing again for the same import queues. Progresumess rasminues fs toma also stop ican ally aftiveer. a any nchunks frome stauting, orrowthat alreadyr thte rrupton.s to CYou celledo not an import still do not toou tky to reume ip, contact support with the p IDge open.
If you return to an import that still shows Processing and it has not advanced recently:
• Refresh the page to update progress.
• You can safely start the import again. This queues a resume and continues from the next unprocessed row. Already imported rows are not duplicated.
• If progress still does not advance after retrying, contact support with the import ID.
