Phase 0
Decide & Plan
Lock scope, success criteria, and the cutover window before any export starts.
-
Risk if skipped: Discovering at cutover that Products or reference lists were assumed but never planned forces re-scoping mid-migration.
-
Risk if skipped: Pulling all history by default can multiply the dataset 5–10x and blow through the cutover window.
-
Risk if skipped: Buying Foundation then discovering the migration needs Audit Log or extra pipelines blocks cutover until billing is escalated.
-
Risk if skipped: Discovering after cutover that the tenant is in the wrong region forces a second migration or a contractual exception.
-
Risk if skipped: Selecting a lower tier and then needing forensic audit evidence after cutover means scrambling for compensating controls.
-
Risk if skipped: Unwritten out-of-scope items resurface as urgent during cutover and derail the schedule.
-
Risk if skipped: Without falsifiable criteria, the migration is never formally complete and tail issues drag on for months.
Phase 1
Pre-Migration Prep
Cleanse the source, build the destination schema, and align the team.
1a. Source-system audit and cleansing
-
Risk if skipped: Importing duplicates means rebuilding Lead-to-Person associations against the wrong record after merge.
-
Risk if skipped: Mandatory-field misses produce error rows at import; without a triage plan you lose visibility into what failed.
-
Risk if skipped: Without a baseline you cannot tell at validation whether 'missing' records were never exported or lost in transit.
1b. Destination Nutshell setup
-
Risk if skipped: Skipping sandbox forces all test errors to occur in production where rollback is harder.
-
Risk if skipped: If Nutshellers do not exist before import, every record is owned by one person and you must reassign tens of thousands of records manually.
-
Risk if skipped: Importing Leads into a missing Stage assigns them to the default Stage and corrupts pipeline reporting.
-
Risk if skipped: Importing into a custom field that does not exist drops the data silently. There is no retry after the import completes.
-
Risk if skipped: Decision values that do not exist in the destination list silently fail to populate the field.
-
Risk if skipped: Missing reference values are silently dropped from the imported record with no field-level error.
-
Risk if skipped: Leads imported before the Product catalog land with empty Product fields and require a second pass.
-
Risk if skipped: Activities referencing an undefined Activity type are rejected at import.
-
Risk if skipped: Email sync firing on partially-loaded data scrambles thread-to-record associations.
1c. People and process prep
-
Risk if skipped: Without a documented rollback owner, indecision drags out a botched cutover instead of triggering a clean restart.
Phase 2
Source Export
Pull complete data from the source system in formats the transform stage can consume.
-
Risk if skipped: Non-UTF-8 encoding causes Nutshell's CSV import wizard to reject the file with an immediate upload error.
-
Risk if skipped: Without source IDs, you cannot reconnect Leads to their People and Companies after the lookup IDs change in Nutshell.
-
Risk if skipped: Without the mapping file, attachments arrive in Nutshell unlinked and require manual re-attachment.
-
Risk if skipped: Without an export timestamp you cannot tell what activity occurred between Phase 2 and cutover.
Phase 3
Transform & Map
Convert exports into Nutshell-shaped files with explicit field, type, and relationship handling.
3a. Mapping spreadsheet
-
Risk if skipped: Without a single source-of-truth mapping document, field decisions get made twice and the second decision overwrites the first silently.
-
Risk if skipped: Mandatory-field violations are the most common cause of error rows during Nutshell CSV imports.
-
Risk if skipped: Re-running an import without a stable upsert key duplicates every record instead of updating it.
3b. Data transformation
-
Risk if skipped: Ambiguous DD/MM vs MM/DD strings get parsed by the importer's locale and silently shift dates by months.
-
Risk if skipped: Text values over 225 characters are silently truncated, losing the tail with no error message.
-
Risk if skipped: Non-UTF-8 encoding rejects the entire file, not single rows.
-
Risk if skipped: Unescaped commas split rows into wrong column counts and the import wizard rejects the row.
-
Risk if skipped: A trailing space or wrong capitalization on a Decision option label drops the value silently.
3c. Relationship and audit-trail decisions
-
Risk if skipped: Reporting that filters on created-at will treat every migrated record as created at cutover, distorting historical trend analysis.
-
Risk if skipped: Loading Leads before Companies strands Leads without their Company link and forces a re-link pass after.
3d. Nutshell-specific transforms
-
Risk if skipped: Conflating Leads with Accounts puts active sales opportunities and closed-customer records in the wrong list views.
-
Risk if skipped: Importing Leads into a Pipeline with mis-set confidence percentages distorts every forecast report from day one.
-
Risk if skipped: Missing reference values are silently dropped from the imported record with no field-level error surfacing.
-
Risk if skipped: Activating sequences before validation triggers email blasts to customers on incorrect data.
-
Risk if skipped: Two distinct John Smiths in the source land as one merged Person in Nutshell unless the import deliberately bypasses the matcher.
Phase 4
Sandbox Test Migration
Prove every transform and load path before touching production.
-
Risk if skipped: Skipping a sample run means production becomes the first place errors surface.
-
Risk if skipped: Broken links are invisible from the Lead list view but show as empty Person/Company columns in reports.
-
Risk if skipped: Extrapolation from a 50-row sample without considering throughput ceilings produces a cutover estimate off by an order of magnitude.
-
Risk if skipped: Skipping sign-off lets unresolved sandbox issues carry into production where the cost of fixing them rises.
Phase 5
Production Cutover
Execute the production load in a tight, sequenced window with idempotent operations.
-
Risk if skipped: Late writes after the freeze produce records that exist in source but not in destination, requiring a manual delta pass.
-
Risk if skipped: A single live sequence can send hundreds of customer emails during the load.
-
Risk if skipped: Posting stage_name instead of stage_id silently puts the Lead in the default Stage.
-
Risk if skipped: Without per-job error logs you cannot tell which records failed and need a re-run.
-
Risk if skipped: Pushing through with a known delta means later types reference records that should not exist.
Phase 6
Validate
Prove the migration is correct before letting users into Nutshell.
6a. Reconciliation
-
Risk if skipped: An unexplained delta indicates either error rows you missed or a parent-link failure that orphaned children.
-
Risk if skipped: Two stages that net to the same total but moved Leads to the wrong bucket distort forecasts.
6b. Relationship validation
-
Risk if skipped: Missing reference values reduce Forecast and segmentation reporting accuracy without an obvious error symptom.
-
Risk if skipped: Files that uploaded successfully but linked to the wrong record are invisible without per-record inspection.
6c. Audit and compliance
-
Risk if skipped: Discovering the Audit Log is empty after go-live means there is no forensic trail of the cutover itself.
6d. User-acceptance check
6e. Sign-off
-
Risk if skipped: Opening to users before sign-off means data errors get found by sales reps mid-call, eroding trust in the new system.
Phase 7
Post-Migration Cleanup
Decommission the source, rebuild what does not migrate, and close the project.
-
Risk if skipped: Leaving the source writable creates two sources of truth and reps will use whichever is faster, scrambling the data again.
-
Risk if skipped: Activating all sequences at once on freshly loaded data can fire bulk customer emails referencing stale context.
Watch list
Risks to track throughout
These risks live across multiple phases — keep an eye on them from kickoff through cutover.
-
Silent reference-list and Decision-option drops
Nutshell does not error when an imported Lead references a Source, Market, Industry, or Decision option that does not exist on the destination list — the field is simply left empty. The failure is invisible at the record level and only surfaces when Forecast or segmentation reports come up short. Pre-populate every reference value in Phase 1b and verify population on a sample in Phase 6.
-
Exact-name-then-email duplicate matcher
Nutshell's import duplicate matcher checks exact name first, then falls back to email. Two distinct people with the same name but different emails get merged into one record unless the import deliberately bypasses the matcher. Source data with shared names (common in B2B account-team rosters) needs a pre-merge dedup pass or an external-ID strategy that overrides the default behavior.
-
Plan-tier feature gating
Nutshell gates pipeline count, custom-field allocation, sandbox availability, and Audit Log by plan (Foundation, Growth, Pro, Power AI, Enterprise). Selecting the plan before mapping the destination schema risks discovering mid-migration that the chosen tier cannot hold the source's pipeline count or custom-field count. Verify every Phase 1b prerequisite against the chosen plan before exporting any data.
-
Reports, sequences, and Goals rebuild burden
Activity Reports, Forecast views, Email sequences, Templates, and Goals do not migrate as data — each must be rebuilt manually in Nutshell. Underestimating this rebuild is a common cause of slipping the Phase 7 timeline. Capture every source report and sequence as documentation during Phase 2 and treat the rebuild as scheduled work, not a cleanup afterthought.
Related
Common migrations to Nutshell
Every link below is a dedicated pair page covering field-level mapping, edge cases, and pitfalls for that specific source-to-destination move.
Pair this with the long-form guide
The complete Nutshell migration guide
Same research, written as prose: data model, import mechanisms, mapping strategy, pitfalls, and partner landscape.