For a developer, it is very painful to rename a picklist value because he needs to check the reference of this picklist value in the existing system including validation rule, workflow rule, apex code etc., but from Spring ’17 release, Salesforce changed the picklist behavior to protect our picklist integrations. Now, each picklist value is represented with a label and an API name (like 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.
Image 1: Picklist value API name automatically created, when you add values to the picklist.
Image 2: We can modify the picklist value’s label and API name by clicking edit link.
Image 3: Preventing Picklist Value API Name from being changed. (go to Administer -> Data Management -> Picklist Settings).
SOQL consideration
1. By default, SOQL query returns with picklist value API Name.
Example:
Select Enrollment_Type__c from Lead
Output:
Billing
2. To get the picklist label via SOQL.
Example:
Select ToLabel(Enrollment_Type__c) from Lead
Output:
Billing Partner
Picklist Metadata API Changes (39.0 and above)
<valueSet>
<controllingField>Status</controllingField>
<valueSetDefinition>
<sorted>false</sorted>
<value>
<fullName>Billing</fullName>
<default>false</default>
<label> Billing Partner </label>
</value>
</valueSetDefinition>
<valueSet>
Schema.PicklistEntry object
Use the PicklistEntry Class to retrieve picklist value’s label and API name dynamically.
Schema.DescribeFieldResult fieldResult = Account.PicklistField__c. getDescribe();
List<Schema.PicklistEntry> values = fieldResult.getPicklistValues();
for( Schema.PicklistEntry v : values) {
     System.debug('Picklist Value Label:' + v.getLabel());
     System.debug('Picklist API Name:' + v.getValue());
}
getLabel() – will return a picklist value’s label.
getValue() – will return a picklist value’s API Name, as it used to do before.
Conclusion:
We can keep the picklist integration safe by referring picklist value’s API name in the apex code, validation rule and Workflow rule etc. So, by any time developer/admin can change the picklist value’s label would not impact/break any integration.
Reference Link:
1. https://developer.salesforce.com/blogs/developer-relations/2017/01/keeping-picklist-integrations-safe-using-api-names.html
2. https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_class_Schema_PicklistEntry.htm#apex_class_Schema_PicklistEntry
