Sometimes the metadata used to represent a change made in Salesforce doesn't quite line up with what the Salesforce UI would lead you to believe. An example of this is picklist values on Standard Fields - for instance, the values of the Account Source field on the Account standard object.
The Salesforce UI makes it look as if the field actually stores the value, but the reality is that the values are stored in another metadata type called a Standard Value Set.
And the actual field definition for Account Source is only a reference to the Standard Value Set.
Understanding the metadata types
To start with, it's important to understand the distinction between different metadata types related to picklists.
Custom field - this metadata contains the definition of a custom field. It includes custom field's picklist values if it's a picklist field that is not based on Global Value Set. The values are defined directly within the field's metadata.
Standard Value Set - this metadata type holds standard picklist values for standard fields on standard Salesforce objects (e.g.
Industryfield onAccountobject, orStageNamefield onOpportunityobject).Global Value Set - this metadata represents a reusable set of picklist values that can be shared across multiple custom picklist fields. So if your Custom field uses a Global Value Set, you'd need to retrieve
Global Value Setmetadata in your Gearset comparison +Custom fieldmetadata (which is a part of Custom object).
How to find changes made in picklists (e.g. picklist values)
To find changes to your picklists, if you're unsure whether to use either Standard or Global Value set, we recommend to run a comparison that includes these 3 metadata types in your custom filter:
1. Custom object (for changes to Custom fields where the picklist values are part of the field's definition)
2. Standard Value Set (for picklist values and other changes to standard fields)
3. Global Value Set (for changes to reusable and shared picklist values)
The above metadata types are by default included in Gearset's Default comparison filter. This should hopefully allow you to find the changes you're looking for.
If it's picklist values you need to find, they should be either under Standard Value Set or Global Value Set metadata type.
Note: If you believe your picklist value(s) should have been retrieved by Standard Value Set or Global Value Set for a specific picklist for an object that your Salesforce user has access to in the org, please try the retrieval via Workbench to confirm the behaviour.
If Workbench can retrieve your picklist values but Gearset can't, reach out to us via in-app chat and let us know so that we can ask for this to be supported.
Structure and configuration of picklist fields
Consider that both the structure and configuration of the picklist fields can affect how their values are retrieved via Metadata API.
Dependent picklist - If a picklist is dependent, its available values are determined by the selection in a controlling picklist. The complete list of its possible values, along with the rules defining which value is available for each controlling value, is stored within the
Custom fieldmetadata of the dependent field itself.To surface the changes made to a dependent picklist, you need to include the
CustomFieldfor that specific picklist in your metadata filter (e.g.MyObject__c.MyDependentPicklist__c). It's also a good practice to include the controlling field'sCustom fieldmetadata in your comparison to make sure the entire configuration is consistent.
Record Type specific picklist values - If your org uses Record Types on the Custom object, the available picklist values can be different for each Record Type.
Note: While the master list of all possible picklist values is defined in the
Custom fieldmetadata, the specific values available for a given Record Type are defined within theRecordTypemetadata. If you are only seeing a subset of values in your Gearset comparison, you may need to retrieve the relevantRecordTypemetadata to surface the available picklist values for that Record Type.
Global Value Set - As mentioned earlier in the article, if the custom picklist is using a Global Value Set, the actual picklist values are not stored within the
Custom fieldmetadata. TheCustom fieldmetadata will only contain a reference to theGlobal Value Set. To surface the values in Gearset, you need to also retrieve theGlobal Value Setalong withCustom fieldmetadata.
Issues with managed packages
Are you looking to retrieve picklist values of a component (e.g. Custom field) that belongs to a managed package?
Make sure that your metadata filter in Gearset includes managed packages (learn more about it in our documentation).
Consider other restrictions - for example, components of a managed package you're attempting to retrieve may belong to an AppExchange package.
Manage package components hidden from the retrieval can be set as "protected" by the package developer. This would impose a restriction of such components not being retrievable via Metadata API (e.g. a protected Custom field on a package object).
Insufficient user permissions
A common blocker is the lack of necessary permissions for the user account performing a metadata retrieval - this is typically a Salesforce user account used to connect your org in Gearset.
To correctly access and retrieve metadata, either user's profile in Salesforce or a permission set assigned to the user must have the following permissions:
API Enabled - this is a fundamental permission required to use Salesforce Metadata API.
Modify All Data - these permissions often give access to view custom field definitions.
Customize Application - this permissions allows users to both access and modify custom settings, this includes custom fields and their value sets. Without this permission it's likely a Salesforce user won't be able to retrieve the definition of a custom field.
Object and Field-Level Security - in some specific API contexts, insufficient object or field-level security for a Custom object and a field in question can potentially prevent access to picklist values.
Trying to delete a picklist value from the target?
Note on deleting picklist values:
It's a documented limitation of the Metadata API deletions of picklist values aren't supported by Salesforce Metadata API.
Instead, the value become inactive when you deploy their deletions from the source environment.
This behavior is the same for Custom Fields - it's because the Metadata API treats Standard and Custom Fields as one type.