All Collections
Guides on deploying specific metadata types
Splitting a complex deployment into stages
Splitting a complex deployment into stages

A guide to merging environments that are substantially different

Jason Mann avatar
Written by Jason Mann
Updated over a week ago

In most deployment scenarios, the source and target Salesforce orgs will be relatively synchronized. Sandboxes refreshed from a production environment or developer orgs based off a shared integration sandbox will generally contain similar code and configurations, with the majority of differences stemming from new features under development.

Sometimes two orgs with very different baselines need to be brought back in sync. For example, a merger between two companies may require the consolidation of their separate production instances. Merging complex orgs that have no common baseline can be more challenging due to the network of dependencies that need to be brought across.

Building orgs from the base up

When faced with these complex merges, it can be tempting to select every change and deploy them at once. This usually results in an overwhelming number of validation failures from Salesforce.

While some of these error messages may be genuine, many will be red herrings caused by a knock-on effect of the complex dependencies in the metadata. A single failed component with numerous dependent items can cause a string of further errors down the line. Gearset's problem analysis will automatically resolve many of these issues, but sometimes a different approach is needed.

Identifying which issues you should start with, which are false positives, and how to break apart the deployment into more manageable chunks can be a slow and daunting process. Luckily, Gearset is here to help!

The five main stages of your deployment plan

The best way to approach these scenarios is to build the org from the ground up, moving the changes across in smaller batches as part of a structured deployment plan. Starting with the core components and layering on the complexity over time will tackle the red herrings at their root cause, and make things much easier to manage.

We generally advise splitting your deployment plan into five main stages, each moving a different subset of the metadata:

  1. Data tier: First, migrate the core components that set the data structure of the org, and on top of which most other customizations are built. This will include Custom Objects, Custom Fields, Custom Apps, Value Sets, Static Resources, Content Assets and Picklists.

  2. Programmability: Next, add the custom code you've built on top of the platform. This is your Apex: Classes, Components, Tests, and Triggers.

  3. Presentation: With the code in place, you can begin updating your modifications to how your end users interact with the platform, such as VisualForce, Lightning Pages and Components, and Layouts.

  4. Permissions and security model: Now it's time to add in the security model to ensure everyone has the correct access. This includes Field-Level Security, Profiles, Permission Sets, Security Settings, Roles, and Sharing Rules.

  5. Other: Finally, migrate any other components or types required. This list will vary, but may include Email Templates, Reports, Static Resources, Flows, Workflows and Documents.

Gearset's dependency analysis is invaluable when planning these steps. Expand out any item in the comparison results to see what it depends on, and what other items depend on it. This helps you map out the core dependencies as you begin to plan the deployment steps, especially in the data tier.

Build a plan to suit your needs

Every company is different, and there's a huge variety in the configuration and complexity of Salesforce environments. Because of this, it's simply not possible to give a prescriptive list of steps that will apply to every use case. 

Treat these five stages as a starting point for planning a more complex merge. You may need to iterate to find a series of steps that works for you and your specific org configurations.

For example, if you have a particularly large org, you may need to split out the data tier deployment in a number of steps. Or if you're working with version control, you might want to use separate branches to collect components for each stage ahead of running the actual releases.

Did this answer your question?