TrustAPI Docs

Archive

Before you can archive data you must enable Backup. Archiving data is a destructive action. Salesforce's Cascade Delete mechanisms and trigger automation may cause more data than you expect to be destroyed. Backup is the best way to guarantee all deleted data, whether deleted by GRAX archives or from any other Salesforce action, is protected in GRAX.

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

What is it?

GRAX Archive allows you to safely delete records from Salesforce while ensuring they remain fully accessible in GRAX for search, visualization, and restore. Unlike a native Salesforce delete, GRAX is built to address common concerns around deletion:

  • Auditability – complete visibility into what was deleted, when, and by whom.

  • Capacity planning – reduce Salesforce storage usage while retaining access to data.

The foundation of archiving is Backup. Backup guarantees that GRAX has the latest version of every record before archiving. This means things like triggers and cascade deletes aren't going to unexpectedly cause data loss.

How does it work?

Step-by-Step Process

  1. The GRAX integration user (with delete permissions in Salesforce, typically Modify All Data) initiates an archive.

  2. GRAX:

    • Identifies the parent object(s) you want to delete.

    • Inspects the object schema to detect child relationships.

    • Prepares a preview (graph or list view) of all records to be deleted.

    • Applies your selected verification method.

    • Issues cascade delete API calls to Salesforce to remove the records.

    • Provides a summary report (counts, errors, orphan cleanup).

  3. GRAX updates its index so those records remain available for search and restore.

What gets deleted?

  • Parent and Child Records – Salesforce cascade delete rules determine which children are removed (e.g., deleting a Case also deletes related Tasks and Events).

  • Files – GRAX proactively deletes orphaned ContentDocument records and files that Salesforce leaves behind, keeping your environment clean.

  • Content Links – ContentDocument, ContentVersion, and ContentDocumentLink are only deleted once their final parent record has been archived. If still linked elsewhere, they remain intact.

Verification Methods

  • Verify records individually with Salesforce – safest method; checks every record via SOQL. Recommended when data might still be changing.

  • Verify Backup is current – faster; relies on Backup snapshots. Recommended for older, stable data sets (e.g., historical EmailMessages).

Archive Sources

You can select data to archive in several ways:

Source Type
Description

Search

Use GRAX Global Search to filter by object, record status, dates, and fields.

Report

Run a Salesforce tabular report stored in a GRAX-accessible folder. The folder, or Report Name, must contain GRAX and the report must be < 100k rows or 100 columns.

CSV

Upload a CSV with an Id column. File size ≤500 MB; first batch ≤20,000 records. Larger sets can be processed with Auto Archive.

Record IDs

Paste up to 200 record IDs for direct deletion.

Query Template

Use predefined templates for objects like Case, EmailMessage, Task, or ContentDocumentLink.

Query WHERE

Provide only the WHERE clause; GRAX constructs the full query. Supports performance tuning.

Archive Options

  • Archive blocking children – force delete even if child records would normally block parent deletion. Without this option you'll see DELETE_FAILED errors for these records.

  • Ignore objects – skip specific objects so they aren’t included in the archive.

Additionally, the Settings page includes global options that apply to all archive operations.

Auto Archive Behavior

  • Any successful manual archive can be converted into an Auto Archive job, which runs continuously in the background.

  • If records repeatedly fail to delete (e.g., permission or schema issues), GRAX automatically delays retries (up to 24 hours) until the issues are resolved.

  • Job runs are tracked, including number of records processed, errors, and skipped entries.

Archive Statuses

Record Statuses

Successful

Record was successfully archived.

Pending

Record is pending because it’s being archived or blocked by an error in a parent record. Blocked records stay pending until they’re retried individually or the parent error is resolved in a future archive job.

Error

Record was not archived due to an error; this could be Salesforce 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 Salesforce or being automatically archived with a linked parent record as is the case with ContentVersion records.

Job Statuses

Completed

Job successfully finished and archived records.

Pending

Job is ready to run and is pending execution.

Setting Up

Job is querying and loading records to set up the job.

Sustaining

Job is waiting for new records that match the job criteria to be archived.

Error

Job did not complete and did not archive any records.

Warning

Job has at least one record that was not archived OR did not find any results.

Disabled

Job has been manually deactivated and is not currently running.

How do I enable it?

  1. Enable Backup

    • Backup must be enabled before Archive can run.

  2. Test with a single record

    • Archive and restore one EmailMessage first. This helps expose any Salesforce permission or object access issues before larger jobs.

  3. Perform your first archive

    • Open the Record Viewer → find an EmailMessage.

    • Click Archive.

    • Keep the default option Verify records individually with Salesforce.

    • Review the confirmation plan (shows parent and child records, plus files slated for deletion).

    • Click Execute. GRAX will:

      • Verify records and related data are backed up.

      • Delete the records and any orphaned files in Salesforce.

      • Update GRAX to reflect the latest status.

  4. Configure archive criteria

    • Use Search, Report, CSV, or query methods to define what to archive next.

    • Set verification and archive options based on your data’s stability.

  5. Enable Auto Archive (optional)

    • Convert a successful manual job into Auto Archive to continuously archive new eligible records.

  6. Monitor dashboards & errors

    • Use the Archive Dashboard to track overall archive activity, storage reclaimed, and error trends.

    • Review statuses to troubleshoot skipped or errored records.

Addressing Auto Archive Job Delays & Record Errors

When errors occur during archiving, GRAX automatically adjusts the schedule to avoid repeatedly retrying the same failing records.

  • Each record encountering an error may increase the delay before the next archive run.

  • The maximum delay is 1 day.

  • Once the errors are resolved, archiving will gradually resume at normal speed.

If you notice your Auto Archive is only running once per day, this usually means a set of records are repeatedly failing. Check for any record errors in the archive job and note the corresponding error message. Fixing or removing those records in Salesforce will allow archiving to speed up again.

You can filter to records that have an error status by navigating to the Archive job in question and switching the record filter to Error :

Archive Use Cases

Deleting Salesforce data without disrupting your dataset or user experience can be challenging. The complexity of Salesforce schemas, relationships, and validation rules makes archiving and restoring higher-level objects difficult.

For example, deleting a single Account can trigger cascade deletes of many child records, and other objects that reference the Account or its children may block the deletion until updated or removed.

To avoid these issues, break your archive plan into smaller steps and work bottom-up in the data model. For standard Salesforce objects, we recommend archiving in this order:

  1. EmailMessage + Attachments

  2. Task

  3. Case

  4. Opportunity

We strongly discourage archiving top-down - for example, trying to delete an Opportunity and expecting all related Cases, Tasks, and EmailMessages to be removed automatically. This approach often leads to validation errors and incomplete deletions.

Archiving EmailMessage + Attachments

EmailMessages and their Attachments are the simplest and most effective records to archive. In most Salesforce orgs, EmailMessages account for the majority of object storage, and their attachments contribute significantly to file storage. Since EmailMessages sit at the bottom of the data hierarchy, they have few relationships that could trigger validation errors, making them safe and straightforward to archive.

Recommended Approach:

  • Configure an archive for EmailMessages only.

  • Leave objects like Case in Salesforce and use GRAX Lightning Web Components to display archived EmailMessages directly on Case records.

Archiving Tasks

Tasks are another simple and effective target for archiving, helping reduce storage and meet data compliance requirements. Many Salesforce orgs have old Task records that no longer need to remain live.

Recommended Approach:

  • Archive Task records only.

  • Leave objects like Case in Salesforce and use GRAX Lightning Web Components to display archived Task records directly on Case records.

Archiving Records with Related Content Documents

Salesforce manages files using three key objects:

  1. ContentDocument – represents the file itself.

  2. ContentVersion – child of ContentDocument; tracks all file versions.

  3. ContentDocumentLink – connects the file to records, users, or libraries.

A single ContentDocument can be linked to multiple records via multiple ContentDocumentLinks. GRAX will only archive the ContentDocument and ContentVersion after the last linked record is archived or deleted.

Scenarios where only the ContentDocumentLink is archived:

  • The ContentDocument is in a Content Library (linked to a ContentWorkspace).

  • The ContentDocument is linked to multiple records, and at least one record remains active.

  • Orphaned ContentDocuments (all linked records deleted or archived) can be Auto Archived.

Directly archiving a ContentDocument removes all related ContentVersions and ContentDocumentLinks.

Frequently Asked Questions

Can records that are archived by GRAX be recovered from the Salesforce recycle bin?

No - Archived records are "hard deleted" by GRAX. Archived records can be recovered by using Restore.

Why is my Auto Archive job not picking up new matching records?

When an archive job is initiated from the Global Search module, any subsequent Auto Archive job will run only as many times as necessary to process the initial batch of search results; it will not continue to search for or archive newly matching records.

To ensure that an Auto Archive job consistently captures new records based on defined search criteria, it must be configured using the Search source within the Archive module.

Why was my Archive job automatically marked as ‘Disabled’?

Archive jobs that fail to identify new records for five consecutive weeks are automatically disabled.

Disabled jobs can be located by navigating to the Archive tab and clicking View Disabled.

Last updated

Was this helpful?