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 total 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 change monitoring. Once you save a filter, it will be available across Gearset in any place that allows you to specify the metadata filter used.
If you change your custom metadata filter
After an automation job has been set up, if you change the metadata types in your custom metadata filter used in the automation job, you have to go to the automation job, select the filter again (after clicking 'refresh filters'), and click save before the automation job picks up the changes to a filter.
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. That means once you’ve created a filter, your colleagues can take advantage of the benefits without having to spend any time making their own.
Creating a custom metadata filter
- From the Compare & Deploy page, click on Manage custom filters from the Metadata comparison filter drop-down next to the compare button
- In the first 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.
- In the second column, you can then specify whether you want to retrieve all of the items within that type, or just a subset. By default, the setting will be on All items. Click this slider to switch it to Named items.
- To add specific items to the filter, enter their names via the Add box. 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.
- You can then specify if you want to include 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.
- 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 (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.
To delete a custom filter, select it from the dropdown, and click the red cross icon. You cannot modify or delete the preset filters (Default, Compare All, None).
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 (123metadata 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 (e.g. Salesforce orgs) 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.