How to find subcomponents of a parent component, like Custom object?
If you're struggling to find your subcomponent (e.g. Custom field), find the Custom object first (hint: it may be in the All items tab), and then expand the components to find the subcomponent.
For example:
If you are looking for a Custom field, Validation rule, Business Process, WebLink (Custom Buttons) or Record Type in the comparison results, note that they are classified as subcomponents of the parent Custom object.
Note: In the Salesforce metadata API terminology, Standard Objects are classed as Custom Objects.
To retrieve these subcomponents, you will need to select them (and the Custom object that they belong to) in the metadata filter.
You can do it in two ways:
Either by selecting the
Custom object(highlighted in red on below image) when you add it to retrieved metadata types. This way Gearset would automatically include all the sub-components:
Or you can click on the gear icon (highlighted in blue) that stands for
Manage custom filters, and on the next page you'd simply include Custom object + all the relevant subcomponents:
Because these items are classified as subcomponents of their parent Custom object, the item you're looking for may only be present in the comparison results as a nested component rather than its own top-level item.
This is particularly likely if the subcomponent shows as No difference in the comparison results, as we make the comparison results more concise by only showing you the most significant items in the main view.
What is the behaviour when the subcomponent item is New, Deleted or Changed?
If the subcomponent item is New, Deleted or Changed, it may be promoted to being a top-level item.
For example, in this org there is a new Custom field called Close_Reason added to the Opportunity object. If we go and look that field up by its name using the filter in the top right corner, it will show in the comparison results as a top-level component (as long as Custom object metadata is added to the filter):
How to find a subcomponent that is identical both in the source and target (meaning = it shows as 'No difference').
Unlike the previous example, if there's another Custom field (named AccountId) that exists both in the source and target environments and is identical, it will show up as No difference in the comparison results.
And in order to find it, you need to first look up the Opportunity (parent) object and then unfold it to check the 'Components' section to find your Custom field.
Or, once you have looked up the parent object (e.g. Opportunity), you can then use the filter in the top right to locate the subcomponent. Then your subcomponent should also show in the comparison results.
What else to keep in mind when searching for subcomponents?
Check the configuration of granular filters available within the comparisons
Sometimes you may narrow down a filter of the retrieved metadata types that are shown in your comparison results, and exclude some items (e.g. Custom field), but then when you try to look up a specific custom field by their name (e.g. Close_Reason) - it will not show up in your results (which is an expected behaviour).
Instead, you'd see a message in the middle of the screen:
"No Custom object items matching Close_Reason found"
This type of message basically means that Gearset wasn't able to identify a Custom object that can be matched with the Custom field of that specific name (Close_Reason).
How to work around this?
A simple solution to that is to check your filters under Metadata type (icon highlighted in blue on above image), and make sure that Custom field is ticked, so that comparison results can display it when you search the field by its name.
When Custom field type is ticked, the behaviour in the app would change instantly. Meaning you'd be able to see the field in your comparison results when searching for the field by its name (as on image below).
The same pattern applies to any other subcomponent you may be searching for within your comparison results.
So it's worth double checking that those granular filters are set up correctly, and that they're not configured to limit your retrieved metadata components to reduce the noise within comparison results, which is a common practice among users who retrieve a large amount of metadata (and their components).
How to find my item's dependencies in the comparison results?
In the comparison results view, quite often your retrieved item may be dependent on other metadata items. Knowing how to find those dependencies is important for when you need to include them in the deployment.
All the dependencies are nested (stored) under their child component. So in most cases, in order to find the necessary dependency, make sure to locate the child component first!
On the below example, we have a Lightning page metadata type named Record_Page, which is a child component.
In other words, it is a child component of its parent Custom object, Account.
When we unfold Record_Page by selecting the arrow facing downwards: 
we're able to click on the Depends on button:
.
That's how we find out that Record_Page (Lightning page metadata type) depends on the Account Custom object.
Note: The parent object (e.g. Account) doesn't have dependencies, it has dependents. So if you select a parent object (component) first, you won't see its dependencies on the drop down list. Instead, you would see the Used by components.
Used by in this context means that a parent object has component(s) that depend on their parent object (e.g. Record_Page that depends on Account object).
It is only when you select a child component (e.g. Record_Page), you would see on the dropdown what other components it depends on.
Can a dependent item have its own dependency?
It is common to see in the comparison results that your dependency (metadata item that is dependent on another item) will have yet another component that it depends on.
For example, in this org (screenshot below):
- Zone Custom field (located within the Account Custom object, which is the reason why its retrieved API name is Account.Zone) depends on another Custom field named Region (retrieved as Account.Region because both Custom fields belong to the same Account object).
- Therefore, Account.Region is the dependency of Account.Zone field.
- And it also turns out that the Account.Region Custom field depends on the Global Value Set metadata named Region.
- By selecting Used by button:
- you can further see which other metadata items the Region Global value set metadata is used by within the org.
Do you need more guidance on locating your subcomponents in the comparison results? Are there any other scenarios we could cover in our documentation?
Let us know in the in-app chat.