What are metadata filters?

When running a comparison between your source and target, the Gearset Default comparison filter includes the most common metadata types, including Custom Objects, Profiles, Permission Sets, and Apex code. If you want more control over which metadata is compared, you can select a different standard filter, or create a custom filter.

Custom filters let you define which types of metadata you want to retrieve, and exclude those you’re not interested in. They allow you to add in the less commonly compared metadata types that aren't included in the default setting, such as Reports, Static Resources, and Documents. Retrieving less metadata means your comparisons will run faster.

As well as choosing the metadata types to retrieve, such as Apex Classes, you can also specify the names of specific items to retrieve using a custom filter. This gives you greater granularity over what to compare.

Custom filters can also be used in automation jobs

Custom filters can also be used for automation jobs, such as continuous integration, and org monitoring. Once you save a filter, it will be available across Gearset in any place that allows you to specify the metadata filter used.

Updating filters in automation jobs

If you edit the custom metadata filter used in the automation job, the job won't automatically use the updated filter.

To update the filter, you'll need to:

  1. Open up the edit job settings.
  2. Click on the Metadata filter tab.
  3. Click Refresh filters.
  4. Select your updated filter from the drop-down menu.
  5. Click Save.

The job will now apply your updated filter for future runs.

Custom metadata filters can be shared with your team

When you save a custom metadata filter, you can choose whether to share it with the rest of your team or make it private.

Custom filters (private and shared) will appear below the standard filters in the filter menu.

Creating a custom metadata filter

  • From the Compare and deploy page in the Metadata deployments section, select the Metadata comparison filter drop-down next to the COMPARE NOW button.
  • Click Manage custom filters...
  • In the Types to include column on the left-hand side, choose the metadata type(s) you want to include by checking the boxes next to their names. You can filter down the results using the box at the top.
  • If you want to have more granularity over which metadata is retrieved beyond the item types, the Items to include/exclude column (in the center) is the place to go. 
  • From here, you can then specify whether you want to retrieve all of the items within a metadata type, or just a subset. By default, the setting will be on All items. You can click this slider to switch it to Named items.
  • If you selected a source and target org in the Compare and deploy screen before clicking on Manage custom filters..., Gearset will automatically list all of the items in that metadata type. (N.B. this is only the case for orgs - we can't populate this list from source control.) You can then simply select which items to include in the comparison using the checkboxes.
  • The column on the right-hand side, Include managed packages, allows you to specify if you want to include metadata related to managed packages in your filter. In the Default comparison filter this is set to None, and in the Compare all filter this is set to All. In a custom filter you can select either of these or Choose, which will allow you to add a list of specific namespaces to include in the comparison. If you've already selected your source and target org we'll load their namespaces and present them as suggestions for you to add to the list with one click.
  • You can also specify which metadata API version you wish to use for this filter (using the box at the bottom). By default, Gearset will automatically identify the highest commonly supported version between your environments. Unless you have a specific reason to override this, we recommend leaving this on Default (highest common version). (Read more about API versions.)
  • Once you have customized your filter, select Save as new filter, enter a name for your custom filter and press Save as to add it to the custom filters list for future use. Click OK to close the window and select your new filter.

Deleting a custom filter

To delete a custom filter:

  • Click Manage custom filters... and select it from the drop-down in the top left.
  • Click the red bin icon on the top right.

Standard metadata filters

Gearset comes with several standard filters:

  • Default comparison (64 metadata types)
  • Default CI comparison (8 metadata types)
  • Default communities comparison (6 metadata types)
  • Compare all (130 metadata types)
  • None (0 metadata types)

The Default comparison filter contains the most commonly compared objects. For the majority of users, this filter will retrieve all of the metadata items you are interested in comparing and deploying between your environments.

To compare all supported metadata types, choose the Compare all filter. This will also include any managed packages.

The Default CI comparison filter includes the most commonly deployed components when setting up a continuous integration job in Gearset.

Identifying the number of metadata items in each category

When creating a custom filter to speed up comparisons, it can be useful to know which metadata types contain the largest number of items to retrieve so you know which types to consider excluding. 

Once you select the source and target orgs on the Compare and deploy screen, Gearset will begin querying Salesforce for the number of metadata items to retrieve in the comparison.

Once this query completes (usually 5-10 seconds) Gearset will display the total number of metadata items.

After the query is complete, opening the Manage custom filters... dialogue will display the number of items to be retrieved in each metadata type. For example, below you can see that there are 83 Custom Objects that will be retrieved using the current filter. Using a custom filter would allow you to specify a smaller number of Custom Objects if you wanted.

Note: Due to the way Gearset breaks up large objects, such as Profiles, into their constituent components, you may see a larger number of items in some categories than you expected. This is not an issue.

Identifying which items to include in your custom filter

When creating a custom filter, it's important to understand the way the Salesforce metadata API works. Many objects have interlinked dependencies, and to retrieve all the metadata you're interested in, you will need to include all of the relevant metadata types. For Profiles, for example, see this support article on which metadata types you need to include in your filter to retrieve particular subcomponents.

If you're not familiar with which metadata types you need to include, we recommend you stick with either the Default comparison or Compare all filters.

For more information, read the Salesforce documentation on the metadata API.

Did this answer your question?