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 aren't 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 Application:

  • 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:
    • Verifies the record and related data is backed up
    • Deletes the provided records and orphaned files
    • Updates 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.

How It Works

Archives 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 are to be deleted for confirmation (you can switch from the graph view to a list view at this point to ensure that relationships intended for archival are checked off)
  • 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

What's 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 Dashboard

The Archive Dashboard provides a graphical view of Salesforce storage usage over time as well as an archive record count.

Archive Dashboard

The "Show Storage Total" toggle displays the sum of object and file storage usage if enabled. If disabled, those two storage types are displayed independently. Similarly to the backup dashboard, the display of each data type can be enabled or disabled by clicking on that data type in the dashboard legend.

Archive Sources

Archive offers multiple source selection options:

  • Query Template
  • Query WHERE
  • Full Query
  • Search
  • Salesforce Report
  • CSV
  • List of Record IDs

What is Query Template?

The Query Template archive source allow you to choose from a list of 4 objects (Case, ContentDocumentLink, EmailMessage and Task) and then select a Template based on the previously chosen object.

This option does not require any SOQL.

What is Query WHERE?

The Query WHERE archive source is similar to writing a SOQL query, but allows the user to provide only the "WHERE" portion of the query. Other portions of the query are then generated by GRAX automatically when the archive runs using the selected object. There are several performance advantages to using query WHERE source selection for Archive over the full query. These include:

  • The ability to auto tune parts of the query to deal with issues like timeouts. For example, GRAX progressively adjusts the LIMIT aiming to fetch an ideal number of records to archive.
  • It allows GRAX to make additional optimizations to improve performance.
  • Testing the query to see if it works and if it has records is faster, since we initially run it with LIMIT 1.

By default these queries are issued like:


But you also have the option to query for a reference field, which is useful to write queries that join on different objects. A common case is to query for a History object, for example:

SELECT CaseId FROM CaseHistory WHERE ...

What is Full Query?

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

  • In the Application, select "Archive" and click New Archive
  • Choose Full Query from the submenu
  • Enter a SOQL statement to select IDs to archive, for example
    • SELECT Id FROM EmailMessage ORDER BY CreatedDate ASC LIMIT 1
    • This selects the oldest single EmailMessage live in SFDC
  • Continue through the Archive Options and Confirmation screen

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, click into the archive job and click on "Set up Auto Archive"; check off the "enabled" option and save the changes which allows the archive job to run as many times as needed until the all records matching the criteria have been archived. This automatically runs the archive job anytime new records matching the criteria are found.

Please note that Auto Archive can only be setup for archive jobs initiated via SOQL query.

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.


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 aren't 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 isn't expected to receive updates so you can archive it faster by picking Verify Auto Backup is current.

Archive Options

Aside from the verification method, you have a few more options to pick when archiving data with GRAX:

  • Archive blocking children: this tells GRAX to delete child records that restrict deletes on their parent, like cases under an account.

    • Without this option you'll see DELETE_FAILED errors for these records.
  • Ignore objects: This holds a list of objects that GRAX skips, both while archiving and restoring data.

    • For archives, this ensures GRAX does not delete nor try to track deletion data for records of these given objects.

Additionally, in the Settings page there are global settings that apply to every archive.

Archive Statuses

  • Successful: Record was successfully archived.
  • Pending: Record is in the process of being archived OR is blocked due to an error with a parent record that the pending record is dependent on. Please note that if a record is in pending status due to it being blocked, it will stay in pending status until a subsequent archive job is run for that record individually or a subsequent archive job is run where the error for the blocking record has been resolved.
  • Error: Record was not archived due to an error; this could be SFDC or GRAX related and the error message for the record will need to be reviewed to find out more information.
  • Skipped: Record was not archived due to it either being previously deleted within SFDC or being automatically archived with a linked parent record as is the case with "ContentVersion" records.


See Archive FAQ for common errors and workarounds.