Using GRAX to delete data from Salesforce


GRAX Archive provides you tooling to easily delete data from Salesforce with confidence.

Archived records are still available in GRAX for search, visualization and restore – just like any other record deleted directly via Salesforce. But by using GRAX to archive records you can count on us to take care of the usual concerns that come with data deletion, like auditing, capacity planning and data integrity.

The foundation for this is Auto Backup, which ensures GRAX has the latest version of all your records. This means things like triggers and cascade deletes are not going to unexpectedly cause data loss.

GRAX strongly recommends you first archive and restore a single EmailMessage to understand the tools and to expose any permission problems deleting and inserting data in Salesforce.

To archive your first record in the GRAX webapp:

  • Enable Auto Backup.
  • In the Record Viewer, look for an EmailMessage record and click the "Archive" button
  • Keep the default option "Verify records individually with Salesforce"
  • Look at the confirmation; that shows a plan with what data and files are going to be deleted
  • Click "Execute" and GRAX will:
    • Verify the record and related data is backed up
    • Delete the provided records and orphaned files
    • Update the record and related data in GRAX to reflect its latest status

After this is done you can open the record again to restore it.

What is deleted

By default GRAX relies on Salesforce to delete related records, via cascade deletes. So when you request a Case to be archived, for example, you'll notice that related Events and Tasks are also going to be deleted.

That aside, the one case where we may delete additional records in an archive is to clean up ContentDocument records that would be left orphaned. This is important because while the cascade delete takes care of deleting files represented by an Attachment, the ContentDocument hierarchy is a bit different and would allow for orphaned records and files to be left in Salesforce.

Archive by SOQL

The GRAX webapp offers another way to archive one or more records by a SOQL statement.

  • In the webapp, select "Archive" which takes you to the "Archive by SOQL" workflow
  • Enter a SOQL statement to select IDs to archive, e.g.
    • SELECT Id FROM EmailMessage ORDER BY CreatedDate ASC LIMIT 1
    • This will select the oldest single EmailMessage live in SFDC
  • Continue thru the Archive Options and Confirmation screen as above.

SOQL queries support LIMIT and default to 100 if not specified, for safety reasons. The max LIMIT of a single archive operation is 10000 records.

To archive more records than this select the option to "automatically re-run after success".

Review your SOQL statements and archive confirmations carefully before running large or automatic archives. GRAX tooling can not detect queries that may impact your business like deleting many open active Cases.
After this you can review any archive job to perform a batch restore.

How It Works

Archive are performed by the GRAX integration user, which requires "Modify All Data" permissions to be able to delete records. Once you start an archive, GRAX:

  • Collects the "parent" object ID or IDs
  • Introspects the parent object schema to collect "child" object IDs based on "master detail" relationships
  • Applies your archive verification choice
  • Generates a preview of all parent and child records counts that will be deleted for confirmation
  • Issues batches of "Cascade Delete" API calls to Salesforce which deletes parents and relationships
  • Provides a summary of how many records were deleted and what errors if any were returned


The recommended way to prevent data loss when deleting records with GRAX is to pick "Verify records individually with Salesforce" when running archives. In this mode GRAX issues SOQL queries to get information about records that may be deleted with the archive hierarchy, and then ensures that Auto Backup has them covered.

This is extremely important when you are not sure about the shape of the data being deleted, or when you are archiving records that may still change.

There is a faster option available, though, for when you know the data being deleted is stable and cannot change. For example, when archiving email messages via a SOQL query that only returns records created years ago, in most environments this record is not expected to receive updates so you can archive it faster by picking "Verify auto-backups is current".


See archive troubleshooting for common errors and workarounds