If you’ve ever been part of a Salesforce migration project, you know it’s not for the faint of heart. Whether it’s objects and fields, data migration, Flow migration, or moving Apex and Lightning Web Components (LWCs), every migration comes with its own tangled web of dependencies, risks, and “gotchas.”
Right now, I’m in the middle of migrating a complex set of Flows between Salesforce orgs, and it feels like solving a puzzle where every piece has hidden dependencies. It’s a reminder that migrations aren’t just technical moves, they’re about strategy, architecture, and creative problem-solving.
In this post, I’ll share a structured way to approach Salesforce migrations, backed by real-world examples and technical insights. My goal is to make this valuable whether you’re a Salesforce developer rolling up your sleeves, an architect designing the big picture, or a business leader trying to understand what a migration truly involves.
Why Salesforce Migrations Are So Challenging
At first glance, migration sounds straightforward: “just move objects, fields, and data.” But the reality is that Salesforce is rarely a greenfield environment.
Objects are deeply intertwined with validation rules, triggers, and automation.
Fields often drive reporting, security, and external integrations.
Flows may reference hardcoded IDs, queues, or record types that don’t exist in the destination org.
Apex and LWCs may be coupled with custom labels, custom settings, or managed package dependencies.
I once migrated a case management system for a healthcare provider. On paper, it was simple: move cases, flows, and user permissions. In practice, we discovered that half the automation referenced queues that were manually named by an admin years ago, and those queues had no counterpart in the new org. The migration plan had to pivot mid-way to create Custom Metadata Type-driven references instead of hardcoding.
This is why migrations need to be treated as strategic architecture projects, not “copy-paste exercises.”
Step 1: Analysis – Mapping the Landscape
Every successful migration starts with analysis. Think of it as surveying the land before building a bridge.
Key Areas of Analysis
Objects and Fields:
Are there formula fields tied to other objects?
Do roll-up summaries rely on child objects that exist only in the source org?
Are field-level security and page layouts consistent?
Data:
How many records are involved?
Are there duplicate accounts or contacts that need merging?
Do records rely on external IDs or surrogate keys for relationships?
Flows and Declarative Components:
Do Flows use hardcoded record type IDs?
Are there references to users or profiles that don’t exist in the target org?
Can large, monolithic Flows be broken into sub-flows?
Apex and LWCs:
Does the code depend on org-specific custom settings?
Are there governor-limit risks in the new environment?
Is the code covered by reliable unit tests (not “happy path only”)?
In one of the migrations, we discovered that a custom object had a field Lead_Source__c with picklist values hardcoded in dozens of validation rules. The destination org had different picklist values. Without proper analysis, those validation rules would have failed silently post-migration. We solved it by replacing static picklist values with Custom Metadata Types, making the solution portable across orgs.
Step 2: Strategy – Defining the Path Forward
Once you know the landscape, you need a strategy.
Strategy Choices
Phased vs. Big Bang:
For large, mission-critical orgs, I recommend a phased approach — migrate one business function at a time.
For smaller, isolated projects, a big bang can work, but it carries more risk.
Migration Order:
Objects and Fields → Data → Automation → Code (Apex/LWC).
This order ensures a stable foundation before bringing over automation and logic.
Tooling Decisions:
Change Sets: Good for small, isolated metadata moves.
Salesforce CLI (SFDX): Best for source-driven migrations with version control.
Gearset or Copado: Ideal for enterprise CI/CD pipelines with rollback, testing, and compliance tracking.
During a global retail Salesforce rollout, we couldn’t afford a big bang. Instead, we migrated customer service processes first, followed by sales automation, and finally marketing automation. Each wave gave us the chance to test integrations, train users, and fine-tune before moving on. This phased strategy reduced risk and gave stakeholders confidence at every step.
Step 3: Architecture – Designing for Scalability
Migration isn’t just about moving metadata; it’s about designing a future-proof architecture.
Key Architectural Practices
Avoid Hardcoding: Replace IDs, queue names, and picklist values with Custom Metadata Types or Custom Settings.
Modular Flows: Break large Flows into sub-flows. Easier to migrate, test, and maintain.
Error Handling: Build robust error logging in Apex and Flows to capture failures in the new org.
Data Architecture: Consider whether objects belong in Salesforce at all. For massive datasets, use External Objects or Big Objects.
Scalability: Design for bulk operations. A trigger that works for 10 records may fail for 10,000 in production.
In one insurance migration, a Flow for claims management was 700+ elements long, a nightmare to debug and migrate. I redesigned it into modular sub-flows: one for intake, one for validation, one for assignment. Not only did migration succeed, but future updates became much easier.
Step 4: Considerations – Planning for Pitfalls
Here are the most common pitfalls I’ve seen — and how to address them.
Data Integrity:
Use External IDs for relationships.
Run reconciliation reports after migration.
Security & Compliance:
Re-validate field-level security and sharing rules in the target org.
For healthcare or financial clients, double-check compliance with HIPAA, GDPR, or SOX.
Performance:
For millions of records, use Bulk API 2.0 instead of Data Loader.
Avoid real-time migration jobs; batch instead.
Testing:
Write robust unit tests for Apex.
Conduct UAT with real business scenarios, not just developer assumptions.
In one financial services migration, bulk data loads kept failing. The culprit? A trigger that queried child objects without selective filters. In the source org, it had only 10,000 records. In the target org, it had 5 million. We rewrote the trigger to use selective SOQL queries with indexed fields, which solved the performance bottleneck.
Step 5: Methods – Tools and Techniques That Work
Here’s my toolbox for different migration layers:
Objects and Fields:
Salesforce CLI (SFDX) for metadata migrations.
Store everything in Git for version control.
Data Migration:
Data Loader for smaller jobs.
Bulk API or ETL tools (MuleSoft, Informatica, Talend) for large volumes.
Always migrate parent objects first, then children (Accounts → Contacts → Opportunities).
Flows and Declarative Components:
Change Sets for small migrations.
Gearset/Copado for enterprise needs with testing and rollback.
Apex and LWCs:
Refactor for bulk safety and error handling before migration.
Ensure unit tests > 85% and cover edge cases.
Personal Insights
While migrating Flows from one Salesforce org to another, there is one recurring headache. Hardcoded references. Things like:
Queue names (
Queue_Support_001) that don’t exist in the destination org.Record type IDs tied to the source org.
User references pointing to inactive or non-existent users.
To solve this, I’ve replaced them with Custom Metadata Types that store queue names, IDs, and record type mappings. This way, instead of hardcoding, the Flow looks up the right value dynamically.
The lesson here: if you’re migrating, build for portability. Don’t just move the problem from one org to another.
Migration as a Catalyst for Growth
Salesforce migrations are complex. They’re not just about moving metadata and data; they’re about re-architecting for the future.
When done well, migrations can:
Improve user adoption with modern UIs and efficient Flows.
Strengthen data integrity and compliance across industries.
Enable scalability for millions of records and transactions.
But when rushed, migrations can create technical debt and frustrated users.
That’s why I encourage every migration team to ask:
Have we analyzed dependencies thoroughly?
Is our strategy phased and realistic?
Does our architecture support scale and flexibility?
Have we planned for pitfalls like data integrity and performance?
Migration is not a burden, it’s an opportunity. It’s the perfect moment to clean up legacy issues, modernize, and set your Salesforce environment on a stronger foundation.
What’s the toughest Salesforce migration challenge you’ve faced: data, Flows, or code? I’d love to hear your stories in comments.
#Salesforce #SalesforceArchitect #SalesforceDeveloper #DataMigration #FlowMigration #LWCMigration #ApexDevelopment #EnterpriseIntegration #SalesforceAdmins #SalesforceEcosystem