Gearset uses the Salesforce metadata API to retrieve metadata from Salesforce orgs. Some metadata items can’t be retrieved over the metadata API, or are limited on which parts of them can be retrieved. This can lead to your comparisons not showing a particular item you’re looking for.
This article explains how to use Workbench to work out why the items aren’t being shown and help determine if it’s a limitation of the metadata API or a behavior that Gearset can improve on.
Salesforce Workbench
Workbench is a simple tool that's popularly used to access an org's metadata. Like Gearset, it communicates with Salesforce orgs via the Salesforce metadata API.
If a component can be read by Workbench on the metadata API, Gearset can retrieve it. If Workbench cannot retrieve the metadata, Gearset also won’t be able to.
This makes Workbench an ideal tool to debug issues where items aren’t being returned in your comparisons, and isolate metadata API limitations.
Step 1: Check the list metadata call
A quick way to confirm if the item you’re looking for can be retrieved over the metadata API is to perform a list metadata call. If it can’t, then you won’t be able to see it in Gearset.
In Gearset, this can be done through the metadata filter dialogue. Once both the source and target orgs are selected on the metadata compare and deploy page, the manage custom filter will populate with named items. In the screenshot below, the Custom Tabs are shown.
If you log into Workbench with the credentials of the source org and the target org, you will (combined) see the same list of items:
Select
ProductionorSandboxlogin (selectingProductionif you have a developer org) and the appropriate API version, and clickLogin with Salesforce.
Once logged in, with the same username as used in Gearset comparison, click on
info, and thenMetadata Types & Components.In the drop-down, select the metadata type.
The components list will mirror the metadata filter named items in Gearset. Note: you may need to add the Workbench lists for the source org and the target org together to see the list in the Gearset metadata filter.
If an item is not listed in the Workbench metadata, you won't see it in the custom filter's Named items, and it may not appear in your comparison results in Gearset.
Step 2: Retrieve the metadata
Once a comparison is completed in Gearset, if you can’t see an item in the results, you can execute a retrieval with Workbench to confirm what the metadata API has returned.
Below, you can see some flows returned in Gearset’s comparison:
To find the equivalent in Workbench:
Select
ProductionorSandboxlogin (selectingProductionif you have a developer org) and the appropriate API version, and clickLogin with Salesforce.Click on
migration, thenRetrieve.
In the
Unpackaged Manifestyou’ll need to create and upload an XML file that has content as follows (changing the metadata type and API version as appropriate):
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>*</members>
<name>Flow</name>
</types>
<version>58.0</version>
</Package>
If you know your item is part of a managed package, provide a comma-separated list of package names in the
Package Namesfield.
Select
Single Package, then hitNext.
Click
Retrieveto kick off the metadata download from Salesforce via the metadata API. You may have to wait a while before the results are returned and the .zip is ready to download.
Once the download has completed, we can see that the flows returned via Workbench correspond to the comparison results returned via Gearset.
With these steps, we can demonstrate that Gearset returns what Workbench returns. So if the items are not returned in Workbench, it will explain why Gearset cannot not find it.
Summary
Hopefully this article will help you answer some questions about why Gearset is displaying the items it does in various stages of the application. This should help you understand if the reason you cannot find an item is an issue with the metadata API or with Gearset.
Note that Gearset breaks some metadata type components down into more manageable subcomponents, so you may see fewer individual items when retrieving components from Workbench.
If your item is not returned by Gearset nor Workbench, you may wish to:
check if the item is supported by the metadata API
check if your item is part of a managed package
investigate with Salesforce to understand why the metadata isn't being returned
If you have concerns that hasn't been covered by this article, please let us know!