# Archive {% hint style="danger" %} Before you can archive data you must enable [Backup](https://documentation.grax.com/protect-data/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. {% endhint %} 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`). * Master-Detail relationships are deleted automatically with their parent record (shown in blue in graph view on Configure step). * Lookup relationships are NOT automatically deleted by default (shown in grey in graph view on Configure step). * 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. ### Managing Lookup Relationships By default, GRAX only considers master-detail relationships to be deleted with their parent record. If your archive includes records with lookup child relationships, you have the option to include those lookups in the archive as well. To include lookup relationships in your archive: * Navigate to the Configure step before archiving. * For each lookup child relationship, click the Review Relationships icon underneath the graph view to identify any records at risk of being orphaned. * GRAX will display a warning if orphaned records are detected when the icon is clicked. A red dot on the icon will be visible if there is a warning. * For example: "Case Relationships – By default GRAX only considers master-detail relationships to be deleted with their parent record. This means the following lookup relationships would leave records orphaned. Check them to include in this archive: Case\_\_c (Case\_Responses\_\_r)" * Select the lookup relationships you want to include in the archive. #### Including Additional Parent Objects The Relationships tab in the List view allows you to select unselected Parent Objects, enabling you to include additional optional objects in your archive. This is useful when you want to expand your archive scope beyond the primary object selection. ### 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 * `Skip Objects` – Will skip specific objects so they aren’t included in the archive. * `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. * `Delete whole email threads` - When deleting an `EmailMessage` record, this ensures we also delete every other email in the thread, even if they don't match your archive criteria. For example, if a single EmailMessage in a thread is related to a Case that meets your criteria, instead of just deleting that one EmailMessage, it deletes the entire thread associated with that EmailMessage. * `Hard Delete` - Also deletes records from the recycle bin. Additionally, the [Settings page](https://documentation.grax.com/other/settings) 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](https://documentation.grax.com/protect-data/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` {% hint style="warning" %} 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. {% endhint %} ### 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](https://documentation.grax.com/reuse-data/managed-package/second-generation/features) 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](https://documentation.grax.com/reuse-data/managed-package/second-generation/features) 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. {% hint style="warning" %} Directly archiving a `ContentDocument` removes all related `ContentVersions` and `ContentDocumentLinks`. {% endhint %} ## 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](https://documentation.grax.com/protect-data/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`. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.grax.com/protect-data/archive.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.