All Collections
Feature guides
Automation and CI
Org monitoring
Change monitoring: automating org change tracking and metadata backup
Change monitoring: automating org change tracking and metadata backup

Get daily org snapshots, change reports and audit history, take on-demand metadata backups and inspect Apex code quality

Pearl Oyunbaatar avatar
Written by Pearl Oyunbaatar
Updated over a week ago
  • Your team needs an Automation Platform license to use this feature

Gearset's metadata change monitoring gives you a detailed audit trail of configuration changes in your orgs on a day-by-day basis, and can take org snapshots on demand to back up your metadata. It also runs static code analysis on your Apex code to provide feedback on the quality of the code you're writing.

It works by comparing daily snapshots of your org's metadata and highlighting any changes. You can also roll back unwanted changes, download snapshots of your org's metadata on-demand, and deploy detected changes to other environments.

Gearset will store the metadata back up for as long as possible, with no expiry to the snapshot stored.

Creating a metadata change monitoring job in Gearset

Before creating an automated change monitoring job, you first need to have added a connection to at least one of your Salesforce orgs.

  • Navigate to the Monitoring page, found under Automation in the nav menu on the left.

  • Click ADD NEW JOB....

  • Choose the time you want the job to take a snapshot of your org each day.

  • Give the job a descriptive name (e.g. 'Production change tracking').

  • Select an org to monitor from the drop-down.

  • Click the Notification settings tab.

  • Choose whether to send notifications every time the job runs, or only when changes are detected.

  • Enter the email addresses to be notified. Gearset also supports SMS notifications (US, UK and Australia only), Slack and Microsoft Teams integration via webhooks, and Chatter integration straight into your org.

  • Click the Metadata filter tab.

  • Specify which metadata types you want your change monitoring job to retrieve from your org. You can select from pre-defined standard filters (e.g. use the Compare all filter to monitor / back up all compatible metadata) or create your own custom filter. (Read more about custom metadata filters here.)

  • Click Save to create the job.

When you first create the job, it will have the status Pending. It will start taking the first snapshot immediately. Once this is completed, the status will update to Initial snapshot taken - you may need to refresh the page to see this. (See the section below for more on change monitoring statuses.)

The job will be queued to run at the time you specified. This will be the second snapshot, so it will then run the first comparison and begin tracking changes. (You can alternatively click Take snapshot to run a snapshot on demand.)

When two snapshots have been taken, you will be able to view the history, track changes, perform rollbacks, and deploy detected changes to another org or version control system.

Viewing job status

The monitoring dashboard page displays a list of the change monitoring jobs created. The STATUS column displays the most recent outcome of the check for changes to an org's metadata. There are various possible statuses for a monitoring job:

  • Identical: comparison succeeded, and no changes have been found between the two most recent snapshots.

  • Different: comparison succeeded, and changes have been found between the two most recent snapshots.

  • Pending: the initial snapshot has not yet been taken.

  • Initial snapshot taken: we have taken the initial snapshot, but haven't performed a comparison yet.

  • Initial snapshot failed: we failed to create an initial snapshot.

  • Snapshot failed: comparison failed due to a failing snapshot.

  • Comparison failed: snapshot was successfully taken, but the comparison failed.

  • Trial expired: the user's trial has expired.

Jobs you own can be run on demand by clicking the Take snapshot button in the ACTIONS column.  (Click on the job first to see the expanded actions list below it.) This will immediately take a snapshot of your Salesforce org's metadata.

When an change monitoring job is created, it is added in an Enabled state. You can stop monitoring jobs from running automatically by switching their status to Disabled. A disabled job will not run unless you click the Take snapshot button. To switch a job between enabled or disabled, click the slider into the desired state.

Viewing detailed monitoring history

Clicking View history will open up the full monitoring history for the job. This will list when each snapshot was taken, its status, and how many items were detected as being changed.

If you want to see what changes were detected on any day, click View comparison. You'll see the same comparison view as when comparing two orgs, but in this case the results will be from the same org at two snapshots in time, 24 hours apart.

Rolling back detected changes

You can roll back detected changes from a monitoring job. This runs a comparison between the saved snapshot and the org's live state, and allows both full or partial rollback of any unwanted changes detected (learn more).

Deploying changes to other environments

Changes detected by the monitoring job can be deployed to other orgs or your version control system. For example, changes detected in Production can be quickly promoted into a testing sandbox or a hotfix branch in source control. 

Click on Deploy changes to... and select the target environment.

This will run a comparison between the snapshot of the source org (that's being monitored) and the live state of the target, and will automatically pre-select the detected changes for deployment.

Downloading a snapshot of your org

Clicking the Download package button will download a ZIP file of the snapshot Gearset took of the org for that day. This can be used as an offsite backup of the org's metadata at that point in time.

Explore profiles and permission sets

To make it easy to track permissions within your Salesforce org, for each monitoring job run you can click on Explore permissions... to view a report.

You can look up permissions either for specific objects/fields, or for specific profiles / permission sets (and you can swap between the two views).

You can also export a permissions report (CSV file).

Monitor changes to unlocked packages

Gearset detects any changes made to unlocked packages, which would be shown in the PACKAGES AFFECTED column. For more on how Gearset helps you work with Salesforce DX unlocked packages, see our blog post.

View static code analysis

Gearset's fully configurable static code analysis automatically analyzes the Apex code in your orgs as part of the change monitoring. The number of static code analysis issues that are detected are shown in the CODE WARNINGS column. Gearset lists/categorizes these issues and provides feedback on how improve your code; to view this, click View code analysis issues.

For each of your Apex classes, you will see the suggestions for how to improve your code. For more information on any warning or suggestion, click the hyperlink to open the PMD page. 

From the monitoring dashboard, you can also view a summary graph of the static code analysis for any monitoring job, so you can track changes over time. You can read more about this feature in our blog.

Filtering monitoring history by date

By default, the monitoring history will display results from the last 30 days. You can change this filter view by clicking on the date range drop-down menu above the results table.

Using change monitoring to capture and redeploy delta changes

You can use change monitoring's ability to capture all the changes made over a certain duration (like a sprint) in a specific Org. If you create the change monitoring job and immediately turn it off, it still takes the initial snapshot of the state of your metadata as described above.

At the end of your sprint, you can manually run the job again, and it will capture the changes made to the metadata types specified in the filter over that period. You can then use the ability to Deploy Changes To and you can deploy these delta changes to a new target.

Change monitoring - FAQs

How to preview new PMD rule violations that were introduced in my org and flagged by my monitoring job?

Currently, when you select the 'View Summary' button on the 'Monitoring Update' email notification received from Gearset, it isn't possible to view or filter out only the new PMD rule violations. Instead, you'd see the list of all the PMD rule violations.

If you need to specifically see the new PMD rule violations, the workaround for the time being would be to download the CSVs for the monitoring org run that flagged those violations, and the previous run, and then identify the rules by looking at differences in both CSV files - when comparing your CSVs a diff tool may be helpful to get you through the process quicker.

Did this answer your question?