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. The import writes all of its rows in one step: either every row that can be imported is saved, or — if the import stops before it finishes — none are. So the progress screen shows a moving bar and “Importing {N} rows. This page updates every few seconds.”, with no count of rows done and no time estimate; it re-reads the import’s status every few seconds.

If an import has no outcome 15 minutes after it started, the progress screen says “This import hasn’t finished after 15 minutes” and offers Retry import. It may still be running; a retry only restarts it if it has stopped, and members are matched by email, so a retry never imports anyone twice. An import can be started 3 times in all. If an import fails, it becomes failed and the progress screen names the cause (see Commit and monitor an import).

Cancelling a running import isn’t available in this release: the progress screen’s Cancel import button can’t be selected. Let the import finish; you can undo a completed import within 48 hours.

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 the summary screen is headed Partial import and shows how many rows need attention. 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. Undoing the import doesn’t remove them (see How import undo works).

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. (Not available yet: MapleGather doesn’t queue a second import behind a running one today — the import status has no “queued” value. This is planned with concurrent-import support (Story 14.1.5, M2, not built yet). Kept as written for that release.)

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.