How migration import works

This page explains what happens inside MapleGather when you run an import — from the moment you upload your file to the moment your members appear in the system. Understanding this helps you make better decisions at the preview stage and reduces surprises after you commit.

How it works: the import pipeline

MapleGather processes imports in a fixed sequence of stages. Each stage has a corresponding job state that you see in the import history list and on the progress screen.

1. Upload and parse

When you drop a CSV or Excel file onto the upload area, MapleGather reads it and extracts column headers and a sample of values from each column. For Excel files with multiple sheets, it reads all sheets. At this point, nothing in your organization has changed — no members have been touched. The import job enters the uploaded state.

2. Column mapping

MapleGather matches your columns to system fields using a rule engine that looks at both the column header name and the shape of the values (for example, a column named “Email” that contains @ symbols is almost certainly an email field). Suggested mappings appear in the field mapping grid for you to review. The job stays in mapping_pending until you select Confirm mappings →.

When you map a column to a field that doesn’t exist yet (for example, a custom field your organization uses), you can create it inline without leaving the mapping screen.

3. Preview computation

After you confirm mappings, MapleGather computes what would happen if you committed the import right now — without actually writing anything. This produces the import preview: a plan that includes exactly how many records would be created, updated, and skipped. The job is in previewing during this calculation.

The preview is safe to inspect and share with colleagues. No member data has been modified.

4. Commit

When you select Commit import, MapleGather begins writing records. The job enters committing status. For small imports (under a few thousand rows) this is nearly instantaneous. For large imports, a progress bar shows how many records have been processed, fed by a live event stream from the server.

If you cancel a running import, rows that had already been committed at the moment you cancelled remain in your system — they are not automatically rolled back. The remaining rows are not written. The job moves to cancelled.

5. Completion and the summary

When the import finishes, the job becomes completed — whether every row succeeded or only some did. A completed job with failures (a “partial success”) looks the same in terms of state but shows an amber header on the summary screen. Successfully imported rows are in your system and are fully functional members.

The summary screen shows a breakdown of what happened and provides the error report download for rows that failed.

What MapleGather handles on your behalf

Duplicate detection: MapleGather compares imported email addresses against existing members to avoid creating duplicates. Matches are flagged for review rather than silently merged.

Relationship linking: If your file includes household or corporate relationship columns, MapleGather resolves links within the file and between the file and existing members. You can spot-check the relationship graph on the preview screen before committing.

Inline creation: Membership levels, custom fields, and tags can be created on the fly during column mapping. These items are created when you confirm mappings, before the preview stage. If you undo the import within 48 hours, items that are no longer used by any other member are removed.

Serial per-org batching: Only one import can be actively committing for your organization at a time. If you start a second import while one is running, the second one queues automatically and starts when the first finishes.

PII safety in the wizard

When the AI migration wizard is involved, it analyzes your column names and value shapes to suggest mappings. It never sends your members’ actual data — names, emails, phone numbers, or any other personal information — to the AI. Only structural information (headers and inferred types) is used.