Introduction to Layered Modules

Layered modules let you manage your core Salesforce setup consistently across all your orgs, while also allowing for specific customizations for different regions or business units.

Key Components

Core Module: Contains metadata that is common across all orgs. This might include standard objects, core business processes, and global settings.
Org-Specific Modules: Contain metadata that is unique to a particular org. This could include custom objects, page layouts, and integrations specific to a region or business unit.

Gearset combines these modules during deployment, ensuring each org receives the correct combination of global and local settings.

This modular approach helps to maintain alignment across Salesforce orgs while accommodating necessary localized differences. It simplifies deployments, reduces manual effort, and streamlines maintenance.

The core module is combined with the org-specific module to create a single deployment package

Why are developer sandbox updates important?

It’s best practice to align your environments to the source of truth after every release. This ensures every org and branch contains all the new development that’s gone into your source of truth.

Keeping your development environments up to date regularly offers many advantages, such as:

More reliable testing. If you’re testing work in a sandbox that isn’t in sync with your source of truth, then you won’t discover every problem before releasing that work. There might be an edge case that causes your work to fail in production.
Decluttered comparisons. If you’re using Gearset’s comparison tool to see the metadata differences between your orgs, having orgs that are massively out of sync will throw up a huge number of differences, and you’ll need to search carefully for the changes you really care about.
Easier deployments. The likelihood of deploying successfully between out-of-sync environments is lower because the metadata in your target environment may not be the right shape to receive the deployment package.
Successful automation. Adding automation to your release pipeline using continuous integration jobs relies on environments that are in sync. CI jobs are designed to automate frequent deployments of incremental changes. The more metadata a CI job is trying to deploy, the more likely it is to fail.
Easier syncing. Updating your dev sandbox regularly reduces the amount of changes in each update, making each individual update more trivial to fix in the case of merge conflicts.

Why can it be hard to manage these in a multi region pipeline?

Developer sandboxes should receive all updates from the core module, because they should have the most up to date version of the core architecture.

They should also receive the most up to date version of the layered module specific to their parent org, because they should have the most up to date version of the org specific architecture as well.

There's a distinction between changes we want deployed everywhere vs only to specific sandboxes (determined by region)
We need to layer core and org specific changes together, without creating duplicates.
We need to combine these layered changes with changes in the dev sandbox, without causing issues for the resulting deployment.

How can you manage this in Gearset?

Gearset tracks any promotions to the main branch and will list them as updates that can be back promoted to your developer sandbox in one click.

There’s no pull request, branch, or merge that needs to be worked through — instead, Gearset will highlight all the changes to your source of truth and the order in which they were shipped. You can then deploy them back to your sandbox in one go or chronologically if there are dependencies between updates.

We’ve applied the same first-class functionality you’ll find in a single org pipeline to our modular multi-org pipelines.
When you merge a change to the master branch Gearset will create an update notification for your sandboxes, as the user you can merge this update back into your sandbox.
When an update is triggered we layer together your changes and combine them with the changes in your dev sandbox, allowing you to remediate merge conflicts before your dev sandbox is updated.

How can I set up dev sandbox updates in a modular pipeline?

You must have deployment level access to the sandbox in question or be a Team Owner to use this functionality.

By default, Dev Sandbox Updates will be enabled for all new developer sandbox environments added to a pipeline. Existing developer sandboxes will need to be re-created to enable this functionality - to do this first delete the existing dev sandbox and then re-create using Add -> Add developer sandbox.

When adding the developer sandbox make sure that you select the layered module region corresponding to the changes you wish to apply to your dev sandbox's Salesforce org.

To check if your sandbox has updates enabled, click into the three dots and check that the enable updates toggle is switched on.

You can also use the toggle to disable/enable updates for a specific Sandbox.

Any promotions merged into your main branch will appear on your developer sandbox as Updates - you can deploy these by clicking the update button.

No additional set up of Git branches or CI jobs is required for this functionality.

How do modular dev sandbox updates work in practice?

An example of a global update:

A set of changes are merged into the core module (within the core folder) on the main branch.
All Production orgs on the final environment are deployed to.
All sandboxes receive an update.

An example of a region specific update:

A set of changes are merged into the EU module (within the EU folder) on the main branch.

Only the EU Production org is deployed to.
Only EU sandboxes receive an update. Other region dev sandboxes ignore this change.

Triggering an update on a dev sandbox

We show only changes associated with the modules on that dev sandbox.
When the update is triggered we combine those changes with the changes on the dev sandbox, by layering the module changes together.

Note that for merge conflicts, the dev sandbox branch will contain layered changes, with the individual module information being removed for each change. This modular information is removed in preparation for deploying to the dev sandbox, and prevents issues with deployments.