The Salesforce Developers website will undergo maintenance on May 29, 2024 from 3:00 a.m. UTC to 10:00 a.m. UTC. The maintenance process may affect the availability of our documentation. Please plan accordingly.

Developers use sandboxes as interim staging environments or to build and test new solutions or add features to an existing app. A prevalent pain point for developers working with sandboxes is keeping metadata changes in sync between their local project workspace and the Salesforce org.

With Spring ’21, Source Tracking is now Generally Available (GA) in all Developer and Developer Pro Sandboxes – making it a snap to keep metadata changes synchronized. With this feature enabled, you can focus more on building your apps, while Salesforce automatically tracks metadata changes between your local workspace and your org.

As a developer, the feature enables you to pull changed metadata to your local project workspace by running sfdx force:source:pull. You can push local changes to your sandbox using the sfdx force:source:push command.

Codey uses Salesforce CLI and terminal to pull and push metadata changes from local project workspace to developer/developer pro sandboxes

A real-life example showing how Source Tracking enhances developer productivity

Pulsar is a fictitious car manufacturer and vendor that uses Salesforce for sales and service. They also use custom-built apps leveraging the capabilities of the Salesforce App Cloud. Pulsar has a well established version control system in place for their org which uses Github. They have feature licenses and settings configured for their Salesforce org which developers can recreate in their dev environments like sandboxes.

Codey, a developer at Pulsar, is tasked with enhancing an existing production custom app. He has a sandbox that mimics the feature licenses and settings used in Pulsar’s production org.

The problem

Codey starts implementing the enhancement to the app by first making the necessary configuration changes in the sandbox using low-code tools. As he’s developing, he starts writing down the names of all the components he has created/changed on sticky notes. Once he’s done, he’s ready to retrieve all the metadata changes to his local project.

Codey references his sticky notes to construct package.xml (or using Org Browser or equivalent third-party VScode extensions). He then writes some custom logic in Apex classes in his local workspace and adds their names to the sticky notes as well. He can now deploy the code and config changes that he pulled to higher environments by reconstructing the package.xml with the additional changes he made locally.

But that’s not all — Cloudy, a Salesforce administrator at Pulsar, made some configurational changes for some FLS permissions later that day but forgot to inform Codey about them. So there’s no way for Codey to know of the changes made by Cloudy unless he decides to retrieve the project again. Additionally, Codey can easily overwrite all of Cloudy’s changes if he deploys his code without retrieving the updates.

None of these situations are ideal for developers to run into. In the world of automation, these are a hassle to deal with and can easily decrease productive time or cause bugs to creep in.

The solution: Source Tracking

If Codey and Cloudy were using Sandbox Source Tracking, they wouldn’t have had any issues because they would’ve known about each other’s changes. Here’s how things would’ve gone with Sandbox Source Tracking.

Codey requests Cloudy, the Salesforce Admin of Pulsar, to enable Source Tracking in their production org. Since Source Tracking has been enabled after the sandbox was created, Codey asks Cloudy to refresh the current sandbox that he has access to. Refreshing also ensures that Codey’s sandbox has all the features and settings as present in Production.

Codey creates a new feature branch from their git repo, where he intends to track all the metadata he is creating/changing for the latest enhancements.

Codey creates a new feature branch for tracking all the metadata changes for all the enhancements he is working on

Follow the below steps as Codey leverages Sandbox “Source Tracking ” to simplify his development workflow.

  1. Codey uses Salesforce CLI (or Salesforce Extension pack for Visual Studio Code) to authorize the current project’s local workspace against the sandbox with Source Tracking enabled.

Codey Authorizes local project workspace against the Sandbox

2. Codey does not want to push all the code from the current branch back to the sandbox since Codey’s sandbox is already a replica of the production and Codey’s current branch state. So he resets the Source Tracking on remote and local project workspaces using sfdx force:source:tracking:reset

Codey resets the source tracking as remote and local project is in sync state

3. He does all the configuration necessary for the new feature in the sandbox, such as adding fields, creating Flows, or changing page layouts.

4. He then pulls down all the changes in one command using sfdx force:source:pull. Notice Codey does not have to handcraft package.xml to retrieve the metadata or manually track them down.

Codey does configuration in sandbox and pulls all metadata to his local workspace using source pull command

5. Finally, Codey updates a couple of Apex classes as a part of the enhancement. He uses VSCode with the Salesforce Extension pack and edits the Apex class file to update them.

6. He pushes these code changes to sandbox using sfdx force:source:push.

Codey updates Apex class on local workspace and pushes to sandbox using source push command

7. Codey also uses sfdx force:source:status commands to make sure he can see his local and remote changes. Luckily he didn’t have any conflicts. Although if he did, the CLI force:source:status command would have shown conflicts, allowing him to resolve them.

8. Cloudy notifies Codey that he has missed configuring FLS permissions for a few permission sets. Codey creates Cloudy’s login in the sandbox and lets him make the changes in the sandbox. Codey can pull in these changes using the same pull command sfdx force:source:pull.

9. Finally, Codey can use the power of git to commit these changes to his feature branch and raise a Pull Request against the integration environments for Testing.

At this point, Codey can quickly push his branch to other Salesforce environments using the Salesforce CLI and executing sfdx force:source:deploy commands.

By using Source Tracking, Codey cuts down on the costs of manually tracking new components as well as changes made by other developers in a shared sandbox. The feature brings the development time down by tracking diffs using the status command, and pushing and pulling just the changed source instead of deploying and retrieving the entire project.

To get started and enable Sandbox Source Tracking, visit the help documentation.

Note that any sandbox refreshes before Feb 15 will revert your sandbox currently on Spring 21 release to Winter 21 release. Hence proceed sandbox refreshes with caution during the Sandbox Preview window. Read more about Sandbox Preview instructions here.

Best practices and considerations

  1. You might presume that the first-time execution of force:source:pull will get you all the metadata in the org. The pull command only brings changed metadata and not everything. If you’re building a lot of platform apps and have significant metadata, consider organizing metadata using unlocked packages along with Source Tracking.
  2. Along with Source Tracking, using a version control system like GitHub to version your Salesforce metadata for platform apps is highly recommended. This way, you can version your changes, track your change history, and review metadata changes before promoting higher environments.
  3. A few metadata types do not support source tracking. These might not have the metadata API available. Hence they may need manual replication in the production environment. Use the metadata coverage report to find metadata types that do not support source tracking.
  4. Don’t mix and match source deploy/retrieve and source push/pull commands. Because these commands do not support Source Tracking, using them with push/pull commands can bring your project workspace into an undesirable state.
  5. If your project workspace ever gets into a weird state, take a peek at the source tracking commands. They allow you to clear either just your local source tracking information or both remote and local source tracking information.

What’s next

We’re happy to share that with the safe harbor in place, the next step in our roadmap is to make Source Tracking available on partial and full sandboxes. We’re also working on making the experience better for developers performance-wise. Additionally, we’re striving to make more and more metadata types available and supported in Source Tracking. Do let us know any feedback on Twitter or the community group mentioned in additional resources!

Complete a Learn MOAR Spring ’21 trailmix for Admins or Developers by March 31, 2021, to earn a special community badge and enter for a chance to win one $200 USD Trailhead Certification voucher. See Official Rules below.

Share what you love about the Spring ’21 Release with the #LearnMOAR hashtag. Also, don’t forget to sign up for Release Readiness Live happening on January 29, 2020.

About the author(s)

Neha Ahlawat is a Product Manager at Salesforce focused on Metadata API, Source Tracking, and Metadata Coverage. You can follow her on Twitter @ahlawat_neha

Mohith Shrivastava works as a Lead Developer Advocate at Salesforce. He is currently focusing on Salesforce CLI, Heroku, and Lightning Web Components. You can follow him on Twitter @msrivastav13

Additional resources

Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS