How to deploy Global Picklist Value Sets in Salesforce

Global value sets are a fantastic tool for Salesforce teams, streamlining both the picklist development process and the end user experience. They also ensure standardization across your data collection process, giving you a better data quality to base analysis and decisions on. But, despite their usefulness, many teams are put off by the difficulty of deploying this metadata type. Read on to learn more about global value sets, when to use them, and how you can deploy them!

What are global value sets?

Imagine this scenario: marketing have inputted a lead with a country calling code of “+44”, indicating that this is a U.K. telephone number. Let’s now say that this lead gets mapped to a picklist on a contact record. If the area code field of the contact record doesn’t have the “+44” as a value, you’ll end up with the error message Picklist Value does not Exist.

This isn’t just a headache for an admin or developer to resolve — it also stalls your end user in sales from following up with this Contact Record until the error is fixed. What’s worse, your end users will be left with inaccurate information that could prevent them from following up with leads.

Global value sets were designed by Salesforce to solve this issue. They’re a group of standardized values that can be applied to different picklists across your org. This makes it easier for an admin to have oversight of workflows and for your end users to become familiar with the picklist values they may face.

There are a few key attributes of global value sets to bear in mind:

• You’ll need to choose values that are logical for all the different picklist fields they’re applied to.
• Global value sets are always restricted and there’s no way to convert them to unrestricted. This is to prevent someone from modifying these shared values, as it will affect picklists across your org. This also means that integrated systems won’t be able to insert new picklist values.
• Despite this, you can still reorder, replace and change the values within the global value set. You can also deactivate or edit individual values if they’re no longer needed.
• You can use global picklist values in validation rules.
• GlobalValueSet components have the suffix .globalValueSet and are stored in the globalValueSets folder.
• They’re handled by the Metadata API.

What’s the difference between a standard picklist and a picklist that uses a global value set?

For teams that haven’t used global picklist value sets before, it’s easier to understand them in opposition to standard picklist values. The key difference between a picklist using standard value sets and one that uses a global value set is the origin of the values. You’ll be used to individually inputting the values for a standard picklist, but global value sets allow you to reference a premade set when you’re building a picklist. This saves you customization time when creating individual picklists, and allows you to affect changes across multiple different picklists if your requirements change.

To your end users, a picklist using standard or global value sets will look identical. This being said, development teams should be aware of a few key differences between deploying picklists that use global value sets and deploying standard picklists.

Why is it hard to deploy global value sets?

While global value sets can be deployed as usual with Salesforce’s Metadata API, there are a few different use cases that require a little more attention than with other metadata types. For example, teams get frustrated that you often can’t convert an existing field from regular picklist to global picklist, and trying to do so returns the error message Cannot change which Global Value Set this picklist uses.

In a select number of use cases, it’s possible to convert an existing picklist into a global picklist by editing the custom field and selecting Promote to Global Value Set. However, the Metadata API can’t support deploying a standard picklist that has been converted into a global picklist, because this is an in-place conversion. Instead, you’ll need to make “destructive changes”: deleting the original standard picklist, and then deploying these alongside the newly created global value set picklist.

Further, Salesforce teams may find that changes they’ve made to their global value set aren’t picked up by some deployment engines. This is because these deployment tools use Last Modified Date as an indication of metadata changes, rather than actually comparing the state of the metadata between source and target orgs to identify which objects have changed and how. As a result, changes to global value sets won’t be picked up, because Salesforce doesn’t consider changed values within the global set as a modification, and so won’t update the Last Modified Date that these deployment tools rely on.

Even when deploying changes only to a global value set picklist, teams consistently run into a few painful errors. Thankfully, these often have straightforward fixes.

Common errors when deploying global value sets

“Global value set in record type on the entity cannot be resolved”

This is a known problem that was caused by Salesforce’s Winter ‘23 release, which appended __gvs to the end of global value set API or Developer Names. Any attempt to deploy metadata with this suffix using Change Sets will fail.

Salesforce did release a patch to fix this issue, which removed the __gvs suffix from global value set names, but if you’re still running into this issue you’ll need to recreate the Change Set and ensure that __gvs has been removed.

“If you are attempting to use a Global Value Set, please use the latest API version available”

This error message arises because of global value set’s predecessor: GlobalPicklist. The GlobalPicklist was introduced in the 37.0 version and is only available in this version of the Metadata API. As a result, any version of the Metadata API, other than version 37, won’t be compatible with a GlobalPicklist. You’ll need to update to a later version of the Metadata API and use global value sets instead.

“Duplicate label for deployment with Global Picklist Value Set”

This is an issue that arises from Change Sets’ logic. Change Sets uses a picklist’s API name as its unique identifier. If you change the API name of your picklist, Change Sets sees this as a new picklist, rather than an updated existing global picklist. As a result, Change Sets will attempt to deploy the picklist with the changed value name as a new picklist — at which point it will encounter the existing picklist and view the new one as a duplicate.

Unfortunately, there’s no workaround for deploying this. Instead, you need to make the change to the value without changing the API name. We have an article for dealing with the similar error message Duplicate picklist value specified: AG.

Picklists causing data deployment errors

There are also some errors with data deployments that arise from issues with picklists. These can be resolved using manual fixes within your orgs, or a smart deployment solution like Gearset.

How to deploy global value sets using Gearset

Deploying global value sets can be tricky, but Gearset’s metadata deployments makes them a breeze. You can deploy global value sets with Gearset’s intuitive metadata deployment workflow, which has some smart functionality to help you deploy them successfully.

If you want to follow along with these steps to deploy global value sets, get 30 days access to Gearset free of charge.

Choose your source and target orgs

To start, you’ll want to move to the Metadata deployment section of the Gearset app and click on Compare and deploy. Once you’ve selected your source and target orgs, select a comparison filter that includes global value sets in your metadata comparison. Our Default comparison filter includes global picklists, global value sets and global value set translations, alongside the most commonly deployed metadata types.

Once you’ve selected your comparison filter, click on Compare now. By comparing the differences between each object, Gearset will flag new, changed and deleted objects. We do this instead of looking at the Last Modified Date tag provided by Salesforce, to give you an accurate view of what’s changed in your orgs.

Gearset will highlight any changed global value sets, and provide a view of any changes in both value set and XML formats.

Select your global value set changes

You can choose to deploy the entire global value set, but sometimes you’ll want to be even more precise. For example, you might need to avoid overwriting existing changes if another team member is working on the same metadata and deploying in the same time frame as you. With Gearset, you can deploy individual parts of your global value set to your target org. To do so, use the XML view to pick the changes you want to include in your deployment. Any unselected part of the global value set won’t be deployed!

Once you’ve selected which changes you want to deploy to your target org, click on Next to be taken to the problem analysis results.

Run problem analysis on your deployment package

Our smart problem analyzers will suggest changes to increase your deployment’s chance of success, including resolutions to common issues when deploying global value sets. These can normally be applied automatically, but we’ll also point out manual fixes that you can make in your org.

We have a few problem analyzers that apply specifically to issues with global value sets deployments. For example, our global value set suffix analyzer will pick up deployments that include the __gvs suffix before they’re deployed and prompt the error message Global value set in record type on the entity cannot be resolved. We’ll suggest that you resolve this before your deployment so that you can deploy successfully the first time.

Deploy your metadata changes

Once you’ve processed the problem analysis results, click Pre-deployment summary to see your final deployment package, give the deployment a name, leave notes for your teammates and update any work-tracking integrations such as Jira. Then click Deploy now to move your metadata changes to your target org. It’s as simple as that!

Happy deploying!

Global value sets are really useful, so don’t let deploying them be a hassle! With Gearset’s metadata deployments and precision deployments, moving changes to your global value sets can be as easy as using them. Start a free 30-day trial with Gearset today to see for yourself!