What are metadata filters?
When running a comparison between your source and target from the compare and deploy page, 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 you can create your own custom filter.
As well as choosing the metadata types to retrieve, such as Apex Class, you can also specify the names of specific items to retrieve using a custom filter. This gives you greater granularity over what to compare.
Gearset remembers your previously selected filter. So, when you select a filter (standard or custom) and then run a comparison with that filter, our app will remember that filter and have it selected when you go to run a comparison again.
Custom metadata filters are used in automation (CI) jobs
Custom metadata filters are also used for automation jobs, such as continuous integration (CI jobs), 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.
You may use two types of metadata filters in your CI jobs:
Saved custom metadata filters that your team have created specifically for your needs (these must be shared, they cannot be private)
Default metadata filters created by Gearset
We recommend you choose which metadata types make sense for your team to deploy in your pipeline with a custom filter.
You should aim to use a single saved filter in all CI jobs in your Gearset Pipeline related to the same repository, unless you have a rare specific use case to exclude some types for a single CI job.
In order to save your CI job with changes made to a filter, you must select a saved custom metadata filter or a default metadata filter to proceed.
Updating filters in automation jobs
Note: When you edit an existing named filter (e.g. your own custom filter), any changes that you make to the filter will apply in all the places where given filter is used (e.g. across all the CI jobs that use the filter).
Filters used in CI jobs can be edited in two places.
On the CI dashboard page:
Click on the CI job and select
Edit settingsNavigate to
Metadata filterstabThen make changes to your filter (by adding or removing metadata types)
Click
Save filter...icon:
On the pop-up window decide whether to "Save your changes as new filter", or "Update the filter with any changes you have made" (the second option essentially amends the existing filter).
Tick the checkbox to confirm that you understand the filter amendment will update all the CI jobs that are using this metadata filter.
Click the
Save filter
- saves the filter.Select
Save CI job
- applies amended filter to your CI job.
Or directly from Compare and deploy page:
Click the dropdown under
COMPARISON FILTERSelect
Manage custom filterstabNext, follow the above steps from points 3 to 8.
Once the filter is updated, the CI job(s) will now use your updated filter for all future runs.
Below is a short demo of amending an existing custom filter used in several CI jobs from CI dashboard page:
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 if you want to make the filter private (available only to you).
Who can edit filter shared with the team?
When a filter is shared with the team, only its original creator or a team owner can edit and save changes to it. Team members can use the filter but cannot make and save changes to it; they can use Save as to save any changes they make as a new named filter.
Custom filters (private and shared) will appear in your filter menu in the My filters section. You can find them below the all the Gearset standard filters:
Creating and saving a custom metadata filter
From the Compare and deploy page in the
Metadata deploymentssection of our app, select theComparison filterdrop-down next to theCompare nowbutton.
Then select
MANAGE CUSTOM FILTERS
In the column on the left-hand side, choose the metadata type(s) you want to include by checking the boxes next to their names or within the metadata list. You can filter down the results using the
Filter metadata typessearch box at the top.
If you want to have more granularity over which metadata is retrieved beyond the item types, the
Items to include/excludecolumn is the place to go. This works for the parent component level only. (For example, you cannot exclude custom fields, only custom objects.)From here, you can then specify whether you want to retrieve all 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. Be aware that if you switch the slider toNamed itemsbefore you have selected your source and target orgs, there will be no items listed and the metadata type will not appear in the comparison.Note: orgs connected via username and password will not populate the named item list in the custom metadata filter (for more information see our Managing Salesforce org connections documentation).
You can then useRefresh comparisonto select your desired items from that metadata type.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 the items in that metadata type. You can then simply select which items to include in the comparison using the checkboxes.Note: The named items in the metadata is cached for 15 minutes, and only refreshed after 15 minutes, to reduce the calls to the Salesforce org.
You can also use the box at the bottom of this column for filtering. For example, you can use regex to create complex item filters.
Click on the drop-down arrow next toObject name(as shown on the above screenshot) and selectRegular expression:
The column on the right-hand side,
Include managed packages, allows you to specify if you want to include in your filter metadata related to managed packages. In theDefault comparisonfilter this is set toNone, and in theCompare allfilter this is set toAll. In a custom filter you can select either of these orChoose, 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 setting at the bottom. By default, Gearset will automatically identify the highest commonly supported version between both of the environments you're comparing. Unless you have a specific reason to override this, we recommend leaving API version set to
Default (highest common version).
Read more about API versions on our blog post about MDAPI versioning.You are now ready to save your custom filter. To do so, just click on
Save filterat the bottom of the filter, then decide whether you want this filter to be available to you only or to the whole team. Don't forget to give it a name before clickingSave filter.
Deleting custom filters
To delete a custom filter from Compare and deploy page:
Click
, and select the filter from the drop down menu.Next, click the
Delete filterbutton:
Confirm your action by clicking
Delete shared filter.
Restrictions for deleting custom filters used in multiple jobs
Custom filters cannot be deleted if they're being used in multiple CI jobs.
When trying to delete such filter, you'd normally see a notification:
This filter can't be deleted as it is currently being used by CI jobs
Gearset allows you to preview what other CI jobs are using the filter - option View CI jobs on the top right corner (screenshot above) in the Edit settings of your CI job.
Once the filter is no longer used by any of the CI jobs, you'll be able to delete it.
Standard metadata filters
Gearset app comes with seven standard or default metadata filters:
Default comparison (63 metadata types)
Basic comparison (6 metadata types)
Default CI comparison (8 metadata types)
Default Experience Cloud comparison (16 metadata types)
Default profiles and permissions sets comparison (15 metadata types)
Compare all (222 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 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.
For detailed information about all our standard metadata filters, feel free to check this article: What is a metadata filter?
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 that you know which types to consider excluding.
Once you select the source and target 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 262 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 to (or if you don't need to retrieve all Custom objects found in your environment).
(Please Note: For Custom objects you can also specify sub-components, such as Custom Field or Record Type, to be retrieved along with their parent metadata which in this case is Custom object).
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, but rather an expected behaviour.
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 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:
How to retrieve Profiles and their components using Gearset's metadata filter
If you're not familiar with which metadata types you need to include in your filter, we recommend you stick with either the Default comparison or Compare all filters.
For more information, read the Salesforce documentation on the metadata API.
We are always improving here at Gearset and adding in support for new metadata types. If there is a metadata type that you are using and we don't yet support, then please contact us in our in-app chat.