Learning objectives

  • Understand what Gearset's problem analyzers do

  • Be able to explore metadata dependencies in org comparisons

  • Understand how problem analyzers work in automated jobs

  • Know where to find out more about individual problem analyzers

You will need

  • To have completed Modules 1 (Gearset app fundamentals) and 2 (Mastering metadata filters)

What are Gearset's problem analyzers?

As mentioned in the Gearset app fundamentals module, Gearset was built to be smart - it doesn't just compare your metadata, it actually understands it. One key part of this is its problem analyzers. But what is a problem analyzer?

Metadata is complex. Most components do not exist in isolation - they reference each other to create the complex functions that you build in the Salesforce platform. 

For example, when you create a new custom field on an object, you also create a set of permissions defining which users can access that field. Those permissions exist as separate metadata components in the org. As the permissions refer to the field, you can't deploy them without it. This linkage is a called a dependency.

One of the most common challenges of deploying configuration changes in Salesforce is ensuring you've included all of the metadata dependencies. A single missing component can cause the entire deployment to fail. Finding and fixing these dependency issues can be time-consuming and requires a deep understanding of the metadata.

To help you work around these issues, Gearset has a series of algorithms that scan through your metadata before it gets uploaded to Salesforce, and look for any missing dependencies, as well as other potential issues that could result in a Salesforce deployment failure. We call these our problem analyzers, and Gearset has well over 50 of them helping fix different deployment blockers.

How do they work?

The problem analyzers are built with a single purpose: make your deployments more likely to succeed.


Each problem analyzer looks for a specific issue (e.g. a type of missing dependency) and helps you fix it. For example, the master-detail problem analyzer looks for any master-detail relationships, and automatically includes the master field even if it is identical between both environments. This works around a known bug in the Salesforce metadata API and allows our users to successfully deploy these changes where, if using Ant or other tools, they would fail.

The problem analyzers run before any deployment in Gearset, whether done manually or as part of an automated job. Each problem analyzer will run through the selected metadata items and flag up any potential issues you need to address in order to make your deployment succeed.

Create two interdependent fields

That's the theory; let's see how they operate in practice. Let's add two fields to your source org, one of which depends on the other.

The first field tracks the discounted value for a product that a member of the sales team might offer to a customer.

  • Log into your source org, and navigate to the Account object and add a new field with the settings below

  • Type: Currency

  • Label: DiscountRate

  • Name: DiscountRate

  • Description: The discounted product rate for this customer

  • Leave the field level security and page layout settings in their default values, and save the field

Time to create the second, dependent field, to track how much this product discount works out as a percentage.

  • Add a second field to the Account object with the settings below

  • Type: Formula

  • Label: DiscountPercentage

  • Name: DiscountPercentage

  • Formula return type: Currency

  • Formula: DiscountRate__c / 100 

  • Description: The product discount as a percentage

  • Leave the field level security and page layout settings in their default values, and save the field

You've now got two new fields in your source org. One provides an option to discount a product value, the other calculates that discount as a percentage. Time to see how that's represented in Gearset.

Explore metadata dependencies in Gearset

Gearset's problem analyzers provide suggestions during the final stages of preparing your deployment. But they're also working behind the scenes all the time by surfacing metadata dependencies right in the comparison viewer.

  • In Gearset, run a comparison between your source org and your target org, using the Default comparison metadata filter

  • You'll see four items in the new items tab: two fields, and two sets of permissions for those fields

  • Gearset can display metadata dependencies for you right in the comparison results. Click the > next to the Account.DiscountPercentage item to expand out the dependency tree

  • It looks like this field depends on something - let's find out what! Click on the > next to Depends on to expand the dependency tree further

  • And there it is - Gearset has identified that the DiscountPercentage field depends on the DiscountRate field

This dependency tree is a really powerful way to explore and understand dependencies between your metadata, and it's all powered by Gearset's problem analyzers. If you can expand out an item and see dependencies listed for it, that means there's a problem analyzer working behind the scenes to understand that metadata item.

Triggering your first problem analyzer

To show how the problem analyzers work during a deployment, let's pretend you didn't know about this dependency between these two fields and just wanted to deploy the percentage field to your target org for testing.

  • Select the DiscountPercentage field and the Permissions for Account.DiscountPercentage__c item

  • Leave the other field and permissions item unchecked - there should be two things in the selected items tab

  • Click Next

  • What's this? What happened to the deployment summary screen that came up in previous deployments?

You've just triggered your first problem analyzer! Let's look at what's happening:

  1. Gearset has detected you are trying to deploy a new field (DiscountPercentage), and that field depends on something else (DiscountRate), but you haven't included the dependent field in your selected items

  2. If you don't include this field, your deployment is likely to fail

  3. To fix this problem, Gearset recommends that you include the dependent field (DiscountRate)

For now, proceed without accepting the suggestion.

  • Leave the box unchecked and click Next then Continue to summary

  • Give the deployment a name and click Deploy

  • Oh no - the deployment failed! Look at the error message and you'll see the item that caused the failure was the DiscountPercentage__c field

  • The error message from Salesforce gives a clue as to what went wrong: "Field DiscountRate__c does not exist. Check spelling." What Salesforce is saying is that this field was looking for something it couldn't find - the DiscountRate field.

  • Let's fix that. Click Back to results

  • Click Next

  • This time, check the box to accept the problem analyzer suggestion, then click Next. (Your deployment summary should now show both fields in the selected items)

  • Click Deploy

  • This time, the deployment will succeed. Your two fields are now in your target org. Time for a cup of tea to celebrate

The power of problem analyzers

This is a very simple scenario - in reality you would likely have known about this dependency and included it in your deployment the first time around. But it demonstrates the concept of how Gearset's problem analyzers work. Imagine if you were deploying hundreds of items, some of which were created by colleagues. It would be extremely easy to miss a few crucial items and block a planned deployment. The error messages from Salesforce are not always quite so helpful in tracking down the issue!

Whenever you deploy changes, Gearset will be there providing a helping hand. It'll suggest things to add into your deployment, things you may need to remove, and offer suggestions for things you may need to make directly in your orgs. You don't always have to accept the changes, but in the majority of cases doing so will make your deployments successful.

Problem analyzers in automated jobs

Problem analysis happens during any deployment in Gearset - whether manual or automated. When running a manual deployment, you can review the suggestions from problem analyzers before continuing. In continuous integration (CI) jobs, all suggestions are automatically accepted

The difference between need and want

If you looked closely at the summary of items to deploy table in the worked example above, you may have noticed that there was something missing - although the DiscountRate field was added by the problem analyzer, the associated Permissions for... item was not. This means that when the field was deployed, it would have had the standard permissions applied to it. 

So why didn't Gearset include the permissions as well?

When looking at what to include in a deployment, there are two broad categories:

  1. Things you need to make the deployment succeed

  2. Things you probably want in the deployment, but aren't required by Salesforce

Number 1 comes down to a binary result: the deployment succeeds, or it fails. You can't deploy a field without its dependencies. Salesforce will reject it.

Number 2 requires intent and meaning. You can deploy a field without setting the permissions. Would you want to? That's another question! Perhaps you have some unfinished work on the permissions that don't want to deploy yet? Perhaps you're testing what the default settings are in different environments? Perhaps you must include the permissions to avoid exposing sensitive data to the wrong people? There is no way for Gearset to automatically know this and do the right thing.

As a result, Gearset's problem analyzers target number 1. Gearset will help include what you need to make your deployments succeed, you just need to check you've got all the things you want.

Further reading

Did this answer your question?