Learning objectives

  • Understand what metadata filters are and their benefits
  • Create, edit, and share a custom filter
  • Use custom filters in automated jobs

You will need

  • To have completed Module 1 (Gearset app fundamentals)

What are metadata filters?

Metadata filters define what types of metadata Gearset will retrieve and compare between your environments. If you're familiar with Ant, they act like your package.xml file. If a metadata type isn't in your filter, you won't see it in Gearset.

Whenever you start a comparison, create a monitoring job, or configure continuous integration, your metadata filter will define what metadata Gearset will compare, so it's important to understand how these work.

Gearset comes with a few pre-defined filters to get you started:

  • Default comparison - a great starting point with the most commonly deployed metadata types
  • Default CI comparison - a more limited subset of metadata for getting started with automated deployments
  • Default communities comparison - all the most common metadata types associated with Salesforce communities
  • Default profiles comparison - metadata types that relate to profiles and permission sets
  • Compare all - all metadata types supported by Gearset, including managed packages
  • None - no metadata will be retrieved

Taking a closer look, the Default comparison filter includes:

  • Standard and custom objects
  • Profiles
  • Permission sets
  • Value sets
  • Layouts
  • Apex classes
  • Lightning pages

But it doesn't include:

  • Managed packages and any items created by a managed package
  • Dashboards
  • Reports
  • Static resources

Why use metadata filters?

To run a comparison between two environments, Gearset needs to download the metadata from the source and target. In Salesforce, this happens over the Salesforce metadata API. The time it takes to download the metadata is linked to how much needs to be downloaded - less metadata takes less time, which means you can view the comparison results more quickly.

The other benefit of controlling which metadata is downloaded is avoiding information overload. In the majority of cases, you don't need to see every single configuration change between two orgs to be able to deploy what you've been working on. If you download less metadata, there will be fewer results in the comparison table which will make finding and selecting your chosen changes faster. 

For these two reasons, metadata filters can drastically speed up your workflow with Gearset.

For example, try running comparisons between your source and target orgs with different metadata filters:

  • Using the Compare all metadata filter, you'll get over 850 results
  • Using the Default CI comparison metadata filter, you'll get around 500 results

Now that you've covered what filters are and why they're useful, it's time to create a custom filter and explore how it affects your comparisons.

Metadata filters in action

Let's add a new image to your source org as part of some branding for a new app you're developing, and then deploy that to your target org using Gearset. For this, you're going to create a custom metadata filter.

  • From the Compare and deploy page in Gearset, run a comparison between your source org as the source, and your target org as the target, using the Default comparison metadata filter
  • In the comparison results, click the All items tab
  • In the search box, enter static resource . You'll see a blank table - no static resources have been found
  • In another tab in your browser, log into your source org via Salesforce
  • In the setup menu, search for  static resource and navigate to the Static resources page, and confirm that there aren't currently any resources in your org. So far, so good.
  • Let's add an image to the org; click New to add a new static resource
  • Name it gearsetlogo  and give it a description of This is the Gearset app logo 
  • Right click on the file below and save it to your computer with the file name gearset-logo.png 
  • Click choose file and select the Gearset logo
  • Click Save
  • In your open comparison in Gearset, click Refresh comparison and then Refresh comparison
  • Once the comparison completes, click the New items tab and...
  • ...that's strange - didn't you just add a static resource to the source org? What's going on?! Time to contact Gearset support?

Hang on a moment. As covered above, static resources aren't included in the Default comparison filter in Gearset. To see it, you're going to create a custom metadata filter.

Create a custom metadata filter

Let's create a custom filter which includes the static resource we just added, and removes some of the other metadata types you're not so bothered about seeing.

  • Click New comparison to return to the Compare and Deploy page
  • Click the Metadata comparison filter box to open the list of saved metadata filters
  • Click Manage custom filters
  • In the Types to include column, double click Select all to deselect all items - notice the total number of types selected has dropped to 0
  • In the filter box, type static and then check the box next to Static resource - notice the total number of types selected has gone up to 1
  • Note the Items to include/exclude box. By switching the slider here from All items to Named items, you could control exactly which static resources are included in this filter. For now, leave this on All items
  • In the Include managed packages box, leave the checkbox on None
  • Click the dropdown arrow next to the filter name and select Save as new filter
  • Name the filter Static resources only  and click Save as
  • Click OK to close the window
  • Select your source and target orgs and run another comparison between them using your new filter
  • Lo and behold, your static resource is now showing up!
  • By clicking the Image, Properties and XML viewers buttons you can switch between different ways to view the item in the viewer
  • Select the static resource and deploy it to your target org, then confirm you can find the static resource in the setup menu of your target org

Accessing saved metadata filters

The next time you want to run a comparison to deploy a static resource, you can select your new filter from the dropdown under the My filters section.

You can add as many custom filters as you like. For example you might want to create a filter per project or per team to help them hone in on what they want to deploy and avoid any unnecessary components.

Sharing metadata filters

After creating your new filter, you may want to share it with the rest of your colleagues so you can all take advantage of it. Gearset is all about helping teams work more effectively together, and filters can be easily shared amongst your team. In fact, they're shared by default when you create them!

Below the My Filters section in the custom filters dropdown you'll see a section called Shared with me. Any filters created by other members of your team will appear in here. Simply click on the filter to use it.

If you want to restrict a metadata filter so it's only accessible to you, you can change its sharing settings from the filter dialogue. Open the filter, and select Only me from the share with menu.

Metadata filters in automated jobs

Custom metadata filters aren't just for manual comparisons. They can be used anywhere you run a comparison or deployment with Gearset - that includes automated jobs such as change monitoring and continuous integration (we'll cover what those jobs do and how to set them up in the upcoming modules so don't worry about how to do this just yet).

When an automated job uses a custom metadata filter, it saves a copy of that filter as part of the job settings. If you subsequently modify the metadata filter an automated job is using, it won't automatically apply the new changes to the job.

For example, say you use the new Static resources only filter to in a continuous integration job. Every time the job runs, it will deploy those resources to its target environment. Then, you edit your metadata filter and add in the Apex class metadata type and save it. This change won't automatically apply to the job - it will continue just deploying static resources.

If you want to update a custom metadata filter that an automated job is using, you need to refresh it from within the job settings. Refreshing the filter will apply all the latest changes to that saved filter to the automated job. 

In the example above, refreshing the filter in the CI job will now mean it includes Apex classes as well.

If you use lots of custom metadata filters across automated jobs, and make frequent changes: remember to refresh the jobs.

Interlinked metadata dependencies

When creating a custom filter, it's important to understand the way the Salesforce metadata API works. Many metadata types have interlinked dependencies, meaning that to retrieve all the metadata you're interested in, you may need to include several of the associated metadata types. 

For example, the metadata returned from the profile metadata type depends on what other types are in the download request. Let's see that in action.

  • Run a comparison between your source org and your target org, using a custom metadata filter that only includes the Profile  metadata type
  • You'll be presented with a totally blank comparison - no metadata as far as the eye can see. What's going on? These orgs definitely have profiles in them, we just deployed some changes to them in the previous module!
  • Refresh the comparison, adding in the Custom object metadata type
  • Suddenly you see not only your custom objects, but a all your profiles as well

To help you understand these dependencies, we've written a guide to which metadata types you need to include in your filter to get the results you're expecting. Even with that guide, if you're not familiar with which metadata types you need to include it's easy to end up with unexpected results in your comparisons. As a result, we recommend you stick with either the Default comparison or Compare all filters when you're first getting started with the app.

Further reading

Did this answer your question?