Org Maintenance: Cleanup – Delete and Deprecate Metadata in Salesforce
Org Maintenance: Cleanup – Delete and Deprecate Metadata in Salesforce

Org Maintenance: Cleanup – Delete and Deprecate Metadata in Salesforce

03/24/2021 by Mario Di Genio
In the mood of spring cleaning, in this post we’ll explore how to clean up your org from metadata and code that is no longer needed. Let’s see what sparks joy!

In our last post we focused on how to manage an org migration and take advantage of the opportunity to clean up some unused features as you move on to a new org. But what if your production environment is not moving anywhere? How do you make sure that what you have is actually used and how do you get rid of the stuff you’re not using anymore? Here we’ll give you some tips on how to detect and clean up the clutter in your org. 

Editor's note: This has become a very popular post since it was written. To build on this learning we're hosting a Lunch & Learn live demo of this process with Mario. Read on for an outline of the cleanup recommendations. You can register to join the demo live or receive the recording after here.  

Refresher: What’s the Difference Between Data and Metadata?

Metadata is the structure of the data, while data is the actual data that you input. For example:

  • Contact object has First Name, Last Name and Address. This is the metadata.
  • A contact record has First Name = “John”, Last Name = “Smith” and Address = “123 Fake St”. This is the data, the different records you create (rows of information).

In Salesforce we consider metadata to be basically all the items you can configure in the Setup menu and that defines the way your organization works and what is available to end users.

In this post we will focus on cleaning up metadata, not data. When you clean up data, you’re looking for duplicated records or inconsistent data (formatting and/or completeness). When it comes to metadata, it’s just a simple question: “Are you using this?”, if yes then keep it, if no then deprecate it (archive it) or delete it. And because it’s metadata, removing metadata (that is not object and/or fields) means you get rid of functionality you’re not using anymore, but the data remains untouched. For example: you may not use a workflow rule anymore, so if you decide to delete it, any data that was modified by that workflow rule in the past will remain in the org as is.

We want to review our org and identify those items that are no longer needed and can be deprecated or deleted. Our goals are to:

  • Make sure end users are not using deprecated components (components that perform outdated functionalities that may no longer align with the business processes).
  • Prevent users from becoming overwhelmed by the volume of options they have when actually some of those options are no longer in use.
  • Make it easier for future development to identify what’s currently valid and in use.

The Clutter: How Did It Happen?

As you set up your org or build a new feature, whether it’s a simple object with its fields and layouts or a complex workflow with subsequent actions, you go through different phases of configuration, testing and refining your process. For example: you create fields you think you need at first in an object, later on you decide not to use them, but instead of deleting them from the object, you just remove them from the layouts. Eventually the fields stay there, unused, not visible to end users in the layouts, but visible when building reports or list views. You forget those were there or if they were part of your feature or not, and that’s when you start the clutter. In addition, every time someone is building something new and they need to review what’s already in the org, they will have to go through dozens, even hundreds of fields, without being able to easily determine which ones are actually in use and that they should pay attention to.

Depending on what your introduction to Salesforce was, the clutter may have been there pretty much from the beginning. Maybe you started creating your features in production directly. This is why we always encourage everyone to create new features or test new settings in a sandbox, so that you have time to try and discard any unwanted changes before the final version is pushed to production. When you decide to go to production, you only send what’s really needed and used without dragging anything that is not part of your solution.

Another scenario relates to end user adoption. Sometimes a feature has a limited life, it serves its purpose for a while and then it’s no longer needed. Sometimes a feature becomes outdated, it no longer follows the business processes and if not updated, it becomes derelict and useless. Sometimes end users do not adopt a feature because the training or knowledge transfer to them was not complete, maybe they never heard of it or heard about it once and never actually saw it again.

The Plan

Overall here’s the plan we will follow:

  1. Review metadata.
  2. Evaluate usage.
  3. Backup metadata.
  4. Test and perform deletion.
Step 1: Identify The Metadata To Review

First and foremost, if you have packages installed from the Appexchange, make a list of them and review with your stakeholders if they are currently in use. These packages are the low-hanging fruit of your org. This usually tends to clear up a lot of the metadata left for you to review. When removing a package you may choose to also delete its objects and fields, or leave them to have a historical record of the stored data.

For the rest of your org you can follow the steps to “Make an Inventory” in our previous post. If you already know if something is in use, then you can skip it in that spreadsheet.

Step 2: Review With Stakeholders

Once you have the list of all metadata to review you may need assistance from stakeholders to determine which elements can be deprecated or deleted. This requires the expertise of users who are familiar with the system and know what they need available. This part could be quite extensive, which is why you want to have your spreadsheet available online, so that users can review this on their own and add their notes.

Declarative Metadata Review

There are different criteria you can apply to determine whether something is “in use” or not:

  • Is it active? For example: validation rules, workflow rules, process builders and flows have a status. If they are inactive and they have been like that for a while, then likely they will not be used anymore.
  • Is it referenced somewhere? For example: if a field is not included in any page layout, or code component or report, then likely it’s not in use. 
    • You can go to a field and press the “Where is this used?” button to get a list of all references of that field.

Screenshot of Field Label and API spreadsheet

  • Since this is something Salesforce only allows you to do on a field-by-field basis, you can look in Appexchange for apps that can do this for all fields of one object at a time (search for keywords “field reference”, “field usage”, “unused fields”). 
  • Does it have information? For example: if a field is blank for all the records ever created of that object, then likely it’s not in use.
  • Has it been used in the last year? For example: if the last record of an object was created 3 years ago, then likely that object (and anything that uses that object) is no longer in use (even if there’s still a tab for it and there are reports created on it).

As a result of the user review you should get a spreadsheet with the usage and decision to keep or delete:

Development Metadata Review

Go through the development metadata in your org (Apex classes, Apex triggers, Visualforce pages, Visualforce components, Lightning Components, etc.) and make a list of all the items that you know are deprecated or not in use and that you want to delete. This is best done by an administrator or a developer who is familiar with the functionality of your org and knows how things are done in the backend. If there’s an item that you’re not sure, mark it for review with somebody else who may know their purpose.

Name and API spreadsheet screenshot

For Visualforce Pages and Components you will see that there’s the “Label” and the “Name” fields. Make sure that the Name is the one you keep to later create the file to delete it. The Label is just to show the user when the page is viewed, but the Name is the unique identifier that can be used to perform a deletion on it.

Org maintenance screenshot

Step 3: Backup! Backup! Backup!

When you are making changes that are not undoable (such as deletion) you have to be prepared beforehand in case you need a historical record of it or to rollback and restore it. So don’t forget to backup the data (if you are deleting objects, fields, etc) and metadata (structure of the objects, fields, workflow rules, flows, Apex classes, Apex triggers, etc.) you are going to delete if you may want to restore it later. You can download the data with reports, or data loader, or any data export tool which are generally available and Administrators are familiar with. For metadata you can use a tool such as Salesforce CLI to download it, which developers are more familiar with. But to keep it simple, here are 3 easy ways to backup your metadata when you are not a developer and you don’t want to install anything in your computer.

Download Metadata Directly From Org

For Apex classes and triggers the easiest way is to go to them in the Setup and press the “Download” button. A version of the file will download to your computer and you can store it safely.

Apex classes in setup for org maintenance screenshot

In the case of Visualforce pages and components, they don’t have a “Download” option, so you can select all the content and paste it in a text file that you can save in your computer.

Visualforce pages for org maintenance screenshot

Lightning components do not have an easy way to be downloaded as they are a bundle of different files. Same with objects, fields, validation rules, they don’t have a downloadable version directly from the Setup. But see below the other options you have that apply to all metadata.

Download Metadata From A Change Set

Another easy way to backup your metadata is: in the source org (where the last version of the metadata exists) create an outbound change set, add the metadata you want to backup, upload the change set to any connected org (another sandbox or production). Once uploaded, you will see that the components you added to the change set will have a “View Source” link:

Org maintenance screenshot

If you click that link you will have the same version of the metadata as when you download it with Salesforce CLI, which is how developers download and backup metadata. You can select the content (what you see in the “Source” section) of each “View Source” link in your change set and paste it in a text file that you can save in your computer:

Partner portal screenshot

This can be done to any type of metadata: declarative or development.

Designate a Sandbox as Metadata Backup

Since a sandbox copies everything from one org to another, you can designate one exclusively to be a backup of the current metadata before you delete the metadata from your source org. The only thing is that you have to make sure you don’t inadvertently delete or refresh this sandbox, which would overwrite the environment and everything you had backed up there. This is also a good solution, since if you want to restore the metadata you can create a change set from this sandbox to any connected org with the backup.

Step 4: Delete Metadata

Most metadata in the Setup has a Delete button. But sometimes in order to clean up an org you need to delete code metadata such as Apex Classes, Apex Triggers, Visualforce Pages, Visualforce Components and Lightning Components. There’s two different processes for deletion of code metadata.

Delete Visual Components

For Visualforce Pages and Components you can press the “Delete” button that appears directly on screen.

Org maintenance screenshot

You will have to confirm the deletion and after confirmation the page or component will be completely removed from the org. This is an undoable action, there’s not recycle bin for metadata as there is for data.

If the page or component is not referenced anywhere then the deletion will work. Otherwise you will get a message such as:

Org maintenance screenshot

You will have to remove the page or component from each place where it is referenced: the page layout, homepage layout, button, Lightning record page, etc. Then you can try the deletion again. This is something that can be cumbersome as one component can be referenced in multiple places and some of those dependencies can be circular, not allowing the elimination completely (in which case you will have to delete it the same way Apex Classes and Triggers are deleted explained further below).

For Lightning Components, you can press the “Developer Console” button and delete the component from there, but that will only delete the front-end (the visual part of the component), not the classes that implement the back-end (functionality part of the component).

Org maintenance screenshot

In the Developer Console press the option File > Delete:

Org maintenance screenshot

and confirm the deletion:

Org maintenance screenshot

The validation of whether the Lightning Component is referenced anywhere else is also checked and you will get a message with the list of places where it is referenced and that it needs to be removed from before attempting to delete it.

In this case there’s no problem in either a sandbox or a production environment to delete visual components. But for Apex Classes and Triggers there’s no “Delete” button in production environments and a different process needs to be followed. Next we’ll see how to delete code metadata from a production environment.

Create a Destructive Change

This method is valid for anything in the org (objects, fields, layouts, flows, etc), any visual component as well as code components that cannot be deleted from the user interface of Salesforce. To specify which metadata must be deleted you need to create a zip file with 2 xml files in it:

  • File “package.xml”: contains configuration for the deployment. You can generate the file with the content as specified below. No other changes needed.
  • File “destructiveChanges.xml”: contains the list of metadata to delete. For every type of metadata (ApexClass, ApexPage, ApexTrigger, etc) you create a node named “type” with a subnode “name” with the metadata type and a “member” subnode with the API Name of each metadata to delete.

Each file must have the following content and structure and be saved with the exact name as below.

File “package.xml” exactly as is with the exact “package.xml” file name:
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="">

File “destructiveChanges.xml” following the format of the “types” nodes and with the exact “destructiveChanges.xml” file name:

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="">

The files created in the previous step need to be compressed in zip format and uploaded with Workbench to perform the deletion.

Tip to Create a Zip File in Mac

There’s a small issue in Macs: when they generate zip files, they add hidden files and folders with names such as “.DS_Store” and “__MACOSX”. If you decompress a zip file like this in Windows for example, you will see these files and folders you don’t see in Mac. Some tools that receive zip files as input do not accept zip files containing these additional files. When deploying Destructive Changes in Workbench to delete metadata you need to create a zip file with the xml files as is without the hidden Mac files or it will fail.

To create a zip file in Mac without these hidden files, use the zip command in a Terminal to zip the files without the “.DS_Store”, “__MACOSX” and other .* files:

Open a “New Terminal at Folder” in the folder your xml files are:

Org maintenance screenshotPaste this command: zip -r . -x ".*" -x "__MACOSX" and press Enter.

Org maintenance screenshot

The zip file called “” you need for your Destructive Change is now created in the same folder without the hidden files.

Deploy the Destructive Change

Now we’re ready to deploy our Destructive Change and delete that metadata.

Go to the Workbench login page: 

Select the environment, the most recent API version and check the agreement to the terms of service.

Org maintenance screenshotIf you are already logged in your org Workbench will detect it and ask for permission to access it:

Org maintenance screenshot

otherwise, Workbench will ask for Salesforce credentials to log into the org.

Go to Migration > Deploy:

Org maintenance screenshot

Click “Choose File” and select the zip file with the Destructive Change:

Org maintenance screenshot

Check “Rollback On Error” and “Single Package”. If there’s an error during deployment, then the org will stay in the same way it was when you started the deployment and no changes will be applied. You can check the “Check Only” option if you just want to validate you’ve built the Destructive Change correctly without actually doing the deletion at the end, just simulating to make sure you have everything needed.

Select Test Level “NoTestRun”. Since you are deleting it would not be necessary to execute any additional tests.

Org maintenance screenshot

Click “Deploy” and the deployment will start. This will take a couple of minutes depending on how much metadata you are deleting.

Org maintenance screenshot

Once the deployment finishes you will be able to see the success of the deletion:

Org maintenance screenshot

In case the deployment fails due to coverage, because maybe you are deleting a test class that provides code coverage, repeat the process but in step 7, select “RunSpecifiedTests” and enter the name of a test class that will have coverage and not cause any issues such as “ChangePasswordController” or “ChangePasswordControllerTest” (whichever exists in your org by default). This is necessary for the deployment to complete correctly. Then the deployment should complete correctly.

Org maintenance screenshot


Keeping your org healthy takes time, but it pays off (sometimes less is truly more). Here are our recommendations to keep up with your org maintenance:

  • Don’t procrastinate, start as soon as possible. Any time you spend cleaning up your org is time saved in future development swifting through things that may no longer be used.
  • Keep a log of all your features: who requested it, what is supposed to do, last time reviewed, anything that can give you an idea of its usage.
  • Make it a recurrent task at least once a year to review the usage of each feature and consider retirement if no longer used or needed.
  • Make regular backups of your metadata to have snapshots of your org configuration after deployment of new features or deletion of deprecated ones.

Make It Happen

Here are some interesting ideas you can vote for:


Here are some resources to learn more:

Lunch & Learn: Watch the Process 

Take your learning to a new level with a live walk-through of this post and a demo of the destructive change process. You can register here to join live on August 25th, 2021 at 12:15pm EST or click-through to access the video of the recording after. 

What do you think of this summary? Is there anything else that should be brought to attention when cleaning up orgs? Tell me all about it in the comments below, in the Salesforce Trailblazer Community, or tweet directly at me @mdigenioarkus. Subscribe to the Arkus Newsletter here to get the top posts of the Arkus blog directly to your inbox.