DevOps & Release Governance

Deleting Salesforce metadata is a migration—not a cleanup task

JSBC Labs22 October 20268 min read

Deletion changes the operating system

A pull request removes an unused field, Flow and Apex class. The diff is shorter, the build is green and the change is described as cleanup. In production, however, deletion can alter stored data, permission assignments, integrations, reports, automation and support procedures. The repository shows what disappeared from source; it does not show every dependency or business assumption that disappeared with it.

Salesforce requires destructive change manifests for Metadata API deletions because removing a local file is not itself an instruction to remove the component from an org. The JSBC Labs position is that this distinction is architectural, not procedural. Every destructive change is a migration from one operating model to another and should carry evidence that consumers have moved, data is protected and recovery is feasible.

Prove that unused means unused

Low activity is not proof of irrelevance. A field may be referenced by a formula, Flow, validation rule, report, email template, integration mapping, managed package, data export or quarter-end process that has not executed recently. Salesforce's Where is this used? capability identifies several metadata references, but no single tool can see every external consumer or human procedure.

Build a dependency dossier before approving deletion. Combine Salesforce dependency views, repository search, Metadata API retrieval, Tooling API analysis, integration catalogues, report ownership and interviews with process owners. Search by API name and by semantics: an external system may call the value customerTier while Salesforce stores Segment__c. Record confirmed consumers, unknowns, owners and evidence dates instead of attaching one screenshot and declaring the component obsolete.

Retire the behaviour before the component

The safest deletion is the final step of a retirement sequence. First stop new consumers. Then move writes to the replacement, dual-read or backfill where required, update permissions and interfaces, observe the old component at zero meaningful use, and only then schedule removal. A component that still receives data is not ready for a destructive manifest, even if the team intends to migrate it later.

Use a deprecation window proportional to risk. A private helper class may need one release; a customer-facing field, integration contract or financial automation may need several business cycles. Publish the replacement and retirement date, identify exception owners and monitor late traffic. Deactivation can provide a reversible intermediate state for some automation, but inactive metadata still creates cognitive load and should not become a permanent graveyard.

Choose pre and post deletion deliberately

Salesforce supports destructiveChangesPre.xml for deletions before additions or updates and destructiveChangesPost.xml for deletions after them. That order matters. If an Apex class references an object being retired, update the class first and remove the object afterwards. A post-destructive manifest expresses that dependency sequence inside one deployment rather than relying on operators to perform steps manually.

Do not default every deletion to post because it appears safer. A replacement may require an old component to disappear before a conflicting name or dependency can be created. Model the target dependency graph, select the correct phase and explain it in the release record. Salesforce also notes that post-destructive changes are processed before tests run, so the test suite must be capable of executing against the final metadata state.

Protect data separately from metadata

Removing a custom field is not equivalent to removing a layout element. The field's values may be needed for audit, reconciliation, analytics or rollback. Salesforce can retain some deleted fields for restoration when they have not been permanently erased, but recovery behaviour varies by component; its documentation notes, for example, that deleted roll-up summary fields are purged through Metadata API deletion.

Export and validate data before the release when a component stores business information. Capture record identifiers, values, relationships, timestamps and the transformation into any replacement field. State the retention location, access controls and deletion date. A metadata backup proves what the schema looked like; it does not reconstruct business data that a destructive change removed or made inaccessible.

Validate the exact destructive package

A sandbox rehearsal is useful only when it uses the same package, manifests, API version, test level and ordering intended for production. Salesforce CLI provides deployment preview, dry-run and validate commands, while Metadata API supports check-only deployments. Validate the complete change rather than deploying additions in one pipeline stage and attaching an untested deletion file at release time.

Run tests that detect remaining references and exercise the replacement behaviour. Salesforce recommends running all local tests when deleting Apex classes or triggers. Add targeted tests for flows, permissions, reports and integrations that the compiler cannot protect. Populate representative metadata and data in the rehearsal environment; an empty sandbox can make a destructive change look safe simply because the consumers and histories are absent.

Keep rollback honest

Salesforce Metadata API can roll back a failed deployment transaction, but that is not the same as a business rollback after a successful release. Salesforce Well-Architected notes that metadata recovery generally requires redeploying a previous version, making version control essential. Recreating a component also may not restore deleted data, identifiers, permissions, automation state or messages already exchanged with external systems.

Write the recovery plan before deletion. Retain the previous metadata, data export, transformation scripts and configuration required to restore service. Define the rollback decision window, approver and verification steps. Where true reversal is expensive, prefer a staged cutover with feature flags or compatibility layers. Calling a redeploy command is an action; recovery means proving that users and downstream systems can operate correctly again.

Make destructive intent visible

A pipeline should surface deletions as a separate risk class. Generate and review the destructive manifest, list component types and names, show dependency evidence and require approval appropriate to blast radius. Do not hide a field deletion among hundreds of regenerated profile changes. A reviewer must be able to answer what is being retired, why now, who confirmed it and which recovery assets exist.

Avoid production settings that permit partial success for destructive deployments. Salesforce CLI explicitly warns against ignoring deployment errors in production because successfully applied components can leave the org inconsistent. Preserve atomic rollback behaviour, capture the deployment result and reconcile the target org with source afterwards. A successful status proves that Salesforce accepted the package; it does not prove that the business migration succeeded.

Verify absence as a production outcome

After release, confirm more than component disappearance. Test replacement journeys with real personas, inspect integration errors, monitor Flow and Apex failures, verify reports and permissions, and reconcile migrated data. Search again for stale references in source and operational documentation. Keep enhanced monitoring through the next meaningful business cycle, not only the first quiet hour after deployment.

Track retirement lead time, failed validations, emergency restorations and components left indefinitely in deprecated state. These measures expose whether the organisation removes complexity safely or merely accumulates inactive metadata. The durable principle is straightforward: retire consumers, preserve information, validate the final state, deploy atomically and verify operations. Deletion is complete only when the old component is gone and the business no longer needs it.