Renaming picklist values in Salesforce.com
Renaming picklist values in Salesforce is a common admin task, but it requires careful planning because picklist values are used in configurations, data, integrations, reports, and automation. Below is a concise guide to the steps and considerations to ensure a safe, consistent rename.
What “renaming” means
There are two common actions: editing an existing picklist value (changing the label) and replacing a value across records (mapping an old value to a new value). In Salesforce, changing the picklist label updates the value shown in the UI for new and editable records. Existing stored API values can be either the same (if label-only change) or different (if you change the actual picklist entry). Understand whether you need to preserve API values or change them.
Where renaming can have impact
Data: Records using the picklist will reflect the new label. If the API (stored) value changes, integrations that rely on the old value will break.
Validation Rules, Workflow Rules, Process Builder, Flow: Any logic that references picklist values must be updated if the value string changes.
Apex code and Triggers: Hard-coded comparisons to picklist strings will fail if the value string changes.
Reports and Dashboards: Filters and bucketing that reference the old picklist text may need updates.
List Views: Filters using the picklist value must be checked.
Formula Fields: Any formulas that test the picklist value require revision.
Record Types and Page Layouts: Some record type assignments and layouts may be tied to specific picklist values.
Managed Packages: If a picklist is part of a managed package, editing may be restricted.
Integrations and APIs: External systems consuming picklist values via API (SOAP/REST/Bulk) will be impacted if API values change.
Data Loader and ETL: Bulk operations that match on picklist values must be aligned.
Pre-change checklist
1. Inventory usage:
Search for references in validation rules, workflows, process builder, flows, apex, report filters, formula fields, and list views.
Identify integrations and ETL jobs that refer to the value.
2. Decide on the approach:
Label-only edit: safest if API values must remain stable (edit the picklist value label in setup without changing the actual stored value).
Replace value across records: use Data Loader, Data Import Wizard, or mass update when you want stored values changed.
Value mapping via Record Type: sometimes better to add a parallel value and migrate selectively.
3. Update documentation and communicate:
Notify users and integration owners of the planned change and timeline.
Update internal documentation and training materials.
Performing the change
In Setup, navigate to the object’s Fields & Relationships, find the picklist field, and edit the value. For global value sets, edit the global set.
If changing API/stored value is necessary, plan a migration:
Export affected records, update the picklist column to new value, and re-import.
Alternatively, use a Flow or Apex to mass update internal records.
Post-change tasks
Update validation rules, flows, apex, and any hard-coded references.
Rebuild report filters and dashboard components if required.
Refresh list views and saved searches.
Confirm integrations and ETL jobs function and update mapping if needed.
Communicate completion and any user-facing changes.
Rollback and mitigation
Keep backups (data exports) before changing stored values.
If unexpected breakage occurs, you can revert by re-importing backed-up values or rolling back metadata changes in sandbox and redeploying.
Best practices
Prefer label changes over stored value changes when possible.
Use global value sets for values reused across objects to centralize changes.
Avoid hard-coding picklist strings in Apex; use custom settings or constants where appropriate.
Test all changes in a sandbox, and schedule production changes during low-usage windows.
Careful planning and testing will minimize disruptions when renaming picklist values and ensure dependent systems and users continue to function correctly.