Up until now, any time an admin renamed a picklist value, integrations referencing the value had to be updated, such as through Data Import & Export, Apex, SOQL, etc. In the Spring ’17 release, we are changing this behavior to protect your picklist integrations. From now on, each picklist value is represented with a label and an API name (similar to the name-value pair data representation):

• Picklist value’s label – displayed in a record through UI.
• Picklist value’s API name – used internally on metadata level.

This new feature allows admins to change what users see when they view and select picklist values on a record, without impacting code that references these values. In the example above, we have a picklist that stores information about different Salesforce releases. Let’s say for business purposes we want to store values for the current release, the previous release, and two releases back. Before Spring ’17, admins had to either update picklist values all the time or store something not exactly user friendly (like “current version”). But as you can see, admins can now rename a picklist value’s label without affecting sharing rules, formulas, flows, and Apex code because the picklist value’s API name will remain the same.

Integration example

Let’s look at the example below. In this Apex code sample you can see how API name and value label are treated differently. In this example, we iterate through picklist field PicklistField__c that I created in my org. I’ve added log lines to display both value labels and API names for each picklist value.

• getLabel() – will return a picklist value’s label.
• getValue() – will return a picklist value’s API Name, as it used to do before.

UI changes

When an admin rename picklist values, there is a choice to rename a value’s label or API name. As you can see on the screenshot below we’ve updated the UI to display edit fields for both.

Preventing Picklist Value API Name from being changed

In addition to the ability to rename a picklist value’s label and API name, admins can block all picklist values’ API names from being changed by setting up a special permission. This feature is useful when you have multiple admins in your org and you want to make sure they don’t accidentally break integrations based on picklist values.

In order to set this permission, administrators can go to Administer -> Data Management -> Picklist Settings in Salesforce Classic Setup.

Now, with the Spring ’17 release and this new knowledge, your integrations are safer than ever!

Additional notes

• By default, the ability to change picklist values’ API names is not disabled
• Picklist Settings are not currently available in Lighting Setup
• When an admin creates a new value, the label and API name are set to the same value

Resources

• Picklist Id-Value pairs – Idea Exchange
• Value Labels Are No Longer Tied to API Names – Spring ‘17 Release Notes

About Author

Vladimir is a former engineer from the team that delivered Global Picklists. He has recently switched to product management and planning to use his deep technical expertise to make life easier for Salesforce admins and developers.