What are metadata filters?

When running a comparison, by default Gearset compares the most common metadata types between your source and target, including Custom Objects, Profiles, Permissions, and Apex code. If you want more control over what metadata is compared, you can create a custom metadata filter.

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

As well as choosing the metadata types to retrieve, such as Apex Classes, you can also specify the names of specific items to retrieve as well using a custom filter. This gives you greater granularity on 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 Refresh filters 
  3. Select your updated filter from the dropdown
  4. Click Save 

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

Custom filters are shared with your team

When you save a custom filter, it's automatically shared with anyone else in your team in Gearset so they can easily make use of your new filters.

Filters created by your team will appear under the Shared with me  section in the filter menu.

Creating a custom metadata filter

  • From the Compare & Deploy page, select the Metadata comparison filter  drop-down next to the compare button
  • Click Manage custom filters  
  • In the Types to include column, 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 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 . Click this slider to switch it to Named items .
  • To include or exclude specific items to the filter, enter their names via in the box at the bottom of this column, using either the Include or Exclude  option. You can also use regex to create complex item filters.
  • If you have selected a source and target org in the Compare & Deploy screen, Gearset will automatically list all of the items in that metadata type (NB 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 final column, Include managed packages  allows you to specify if you want to include metadata from managed packages in your filter. Selecting the Choose radio button will allow you to add a list of namespaces to include in the comparison. If you've already selected your source and target org we'll also load the namespaces present in those orgs 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. 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)
  • Enter a name for your custom filter and press Save  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 dropdown in the top left
  • Click the red bin icon

Default metadata filters

Gearset comes with several default filters:

  • Default comparison (64 metadata items)
  • Default CI comparison (8 metadata items)
  • Default communities comparison (6 metadata items)
  • Compare all (127 metadata items)
  • None (0 metadata items)

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 deployment 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 locations of your metadata from the Compare & Deploy screen, Gearset will begin querying Salesforce for the number of metadata components to retrieve in the comparison.

Once this query completes (usually 5-10 seconds) Gearset will display the total number of items to retrieve underneath the org information as well as in the metadata filter dialogue.

After the query is complete, opening the manage custom filters dialogue will display the number of components to be retrieved in each item type. For example, below you can see that there are 513 Permission set entries and 5643 Profile entries that will be retrieved using this current filter and the two selected orgs. Using a custom filter would then allow you to specify a smaller number of permission sets if you wanted.

Note: Due to the way Gearset Break up large objects, such as Profiles, into their constituent components, you may see a larger number of items in some categories than you may expect. 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 item types. Including just Profiles for example, will not return any results if you don't also include items such as Custom Objects.

If you're not familiar with which objects 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?