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:
- Open up the edit job settings
- Select your updated filter from the dropdown
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 filterdrop-down next to the compare button
Manage custom filters
- In the
Types to includecolumn, 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/excludecolumn 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
- 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
Excludeoption. 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 packagesallows 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
Saveto add it to the custom filters list for future use. Click
Okto close the window and select your new filter.
Deleting a custom filter
To delete a custom filter:
Manage custom filtersand 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.