Changing a Field, or any other component's API name is a high risk operation in Salesforce that can lead to significant issues. It's best to avoid it unless absolutely necessary, and if you must, plan carefully and test thoroughly.
However, there could be several occasions when a development team decides to rename the API name of a Salesforce component especially Custom Objects and Custom Fields. The reasons could be any or more than one of the following:
Migration to a new system/org that requires the new naming convention.
To correct poor naming conventions of legacy Salesforce application.
The API name is not descriptive enough to make it readable, and to integrate with other interfacing systems.
Note: One cannot rename API name of Standard Fields and Objects in Salesforce.
Considerations to make before renaming API name of a Salesforce component
Impact on code integrity - Renaming an API name can break the existing code, Trigger, Pages, or Flows where the existing API name is referenced.
References - One need to remove references of this existing API name in whole of the metadata/codebase or source repo. This includes if there are any web service callouts via Apex in which case those references need to be updated with the new API name.
Picklists - Changing the API name of a Picklist Value will update the Value in every record that has that Value selected, but this change won't be logged in Field history tracking, and won't trigger Workflows or other automations.
Requires well-planned deployment - There could be validation issues if all metadata changes related to the API renaming activity are not bundled in the same package when deploying to target org. If you are using version control, and the branch which is used to deploy changes to the org does not contain all metadata which is referencing the new API name, then neither a whole branch deployment nor delta deployment would succeed.
Impact on data integrity - Any ETL process or data migration would be affected if necessary updates are not made with new API name.
Testing - API renaming changes most parts of Salesforce metadata and code, therefore it becomes essential to retest existing functionalities (both functional and regression) after the API renaming activity is carried out, and deployed to test environments.
Existing data records - When you change the API name of a Field in Salesforce, existing data records will retain their values.
Can you avoid API renaming and just rename the Label or description of the component?
If the requirement is to change what end users see as Field name on their UI (e.g. in Page Layouts) then changing the 'label' or the description of the Custom Field is less invasive than changing API name of that field.
Recommended way on handling API rename in Salesforce and promoting such changes through Gearset pipeline
(Renaming API name of a custom field is taken as an example to discuss the following)
Justify the need of API renaming of a Custom Field based on the reasons discussed in the section above should be your first step.
Assess all the impact of changing the API name including development and testing effort, risks, timing, and business value.
API renaming of a Custom Field should be driven the same as any other User Story/Issue in a sprint. Create a User Story in your ALM (Jira/ADO/Asana), providing all the details of which Field's API name is changed. Both the new and existing name, list which all other components references this API name requires updating, which test cases requires to be run to test the functionality, and integration impacted due to updating apex code, flows, pages etc.
Make other team members, other development teams, integration teams, and CAB (if applicable) aware of the change being planned as part of particular sprint well in advance. This helps the respective teams be ready to integrate and assess impact when such changes land in the integrated test orgs.
The development of the API rename story would start in a Developer's Sandbox, first by removing or commenting out references of the existing API name of the Custom Field from all of the metadata that references it. For example from the Apex classes, Visualforce pages, Triggers, etc. Alternatively, one can use Visual Studio Code IDE with the Salesforce Extension to search whole of the org's metadata that has references to the existing API name and update them with new API name.
Rename the API name of the Custom Field from the old to new value in the Sandbox.
Update all the metadata that has references to this Field to the new API name.
Create a new feature branch from
mainusing the Pipeline UI.Using Compare & Deploy, select all the metadata items that are
New,Changed, andDeletedas a result of field API rename. In the comparison, you would see theNewField metadata item, aDeletedField metadata item, and all other metadata items that haveChangeddue to the renaming. Select all relevant metadata components from the comparison screen, and commit them to the feature branch.Ensure all the CI jobs used in the Pipeline has
Deploy Deleted itemschecked.Open a new Pull Request to next adjacent Org branch in the Pipeline.
The Delta package will contain all the changes related to the renaming API name of the Custom Field, including the destructive change to delete the old Field. Upon raising the pull request, the validation of this pull request kicks off and Apex tests run as part of that validation process.
Once validation and other status checks have passed, the pull request can be merged/promoted, deploying the feature to the target Salesforce environment. This delta CI run will deploy the package containing the Custom Field with new API name, and all the updated metadata. At the end of the deployment run, Gearset will make the post-destructive change to delete the Custom Field bearing the old API name from the org.
The feature branch changes can be moved to all of the other orgs in the Pipelines (including Production), as per the usual Pipeline workflow.