Let's take a look at different ways and options you have for restoring records back into Salesforce using GRAX.


The GRAX Restore functionality is a great way to restore a record based on that record's values the last time it was backed up (i.e. sent to GRAX). Restore will not overwrite existing fields with null values (if you truly wanted to go back to a point in time and also clear out any new fields that might have been created etc, you can use time machine for specific records).

Let's take a look at some different ways and places within the GRAX Salesforce app that you can call the restore functionality.

Remember to check out the Restore Logs for detailed information and status of your restore job.

Search and Restore

The primary way users restore data with GRAX is via the Search tab. This tab will let you search your GRAX data, filter on a variety of characteristics, and take action such as restoring or recreating. Note that recreating is different from restoring!


Async-Worker Dyno (GRAX 3.0 and 3.1 Only)

  • In order to maximize resiliency and traceability, the restore process will run through your heroku async-worker dyno. Be sure the dyno is on before attempting any restore.
  • For larger restores, you may want to work with GRAX Support to ensure the dyno settings are optimized for maximum speed.


Worker Index (GRAX 3.0 and Later)

For Admins, the graxgrax_asyncworkerindex will index the status and results of the restore for each root/parent element (not the potential children that will be queried at runtime depending on restore settings)


  1. Go to your Salesforce environment where you have installed the GRAX Application
  2. Click on the tab GRAX
  3. Click on the sub-tab Search
  4. Select the GRAX Table, or Salesforce object, which you want to restore
  5. Select the fields which you would like displayed with your search results
  6. Enter any filter criteria to limit results that are returned
  7. Click Retrieve
  8. Set the necessary toggle switches and options as needed. Please see Restore Options for a detailed explanation of each setting.
  9. Use the checkboxes along with the Restore button to restore record(s). You can also use the "quick restore" icon for any given search result.
  10. You will see a pop-up indicating the ID of your restore job. It will run asynchronously depending on the timer set in your application configuration (typically every minute).
  11. Monitor the Logs > Restore Logs tab for detailed information about records being restored.

Let's search and quick restore an Account, and navigate to the Restore Logs to see status and history of all restored records


Restore All

You can click to restore individual records or use the Restore All button to restore all results of your query. You should have a full count of all results in the bottom right of the search results table.

Restore Using Custom Hierarchy


You will see this feature in GRAX 3.30 and later

Within the Restore Options page, you will now (initially) see a greyed out section named Restore Using Custom Hierarchy. By default, restores will restore only parent records. Once you enable the toggle to restore parent and children, this section will now become available. You can activate this section using the toggle within the section header, which will load the object's hierarchy, in the same way you see when scheduling a hierarchy process. Simply choose the child objects within the hierarchy that you want restored.



  • When you select a child in the hierarchy, notice that the parent object will automatically be selected, in order to comply with the Salesforce relationship structure.
  • Once you enable the custom hierarchy option for a restore, it will only restore objects selected in this hierarchy. If you want to restore infinitely down the hierarchy across all objects, do not use this feature, and instead simply toggle the first option in the Settings section so that the current state is Restoring Parent Record and Children.
  • You do not need to explicitly save the page when setting any of the toggles or restore hierarchy; GRAX is only using these options for the particular session and not saving for all time (the Restore Mapping section on the other hand does have a Save button and will be remembered across all restores).

Enabling the first toggle will restore all children infinitely down the hierarchy. However, you can then activate the custom hierarchy restore and select specific children only.

Restore Mapping

  1. Go to your Salesforce environment where you have installed the GRAX Application
  2. Click on the tab GRAX
  3. Click on the sub-tab Search and then the button for Restore Mapping
  4. Select the GRAX Table, or Salesforce object, that you want to create the mapping for
    a. If this environment, and the related GRAX Runtime, has backed up data from multiple Salesforce environments, you will have the ability to select which Salesforce environment you would like to create the mapping for. This would be done by selecting the checkbox "Would you like to define a custom field Mapping for a source Organization?" and then choosing the applicable Salesforce environment.
  5. Displayed will be three columns:
    a. Mapped fields: all fields which have been mapped from environment to environment
    b. Un-mapped fields: all fields which have NOT been mapped from environment to environment
    c. All fields: all fields regardless of if they have been mapped or not.
  6. Once one of the options have been selected, you have the ability to map fields from within the GRAX datalake to a field in this Salesforce environment.
    a. Find the field that you want to map and then click the box in the column Datalake field
    b. Select the field name, API name, from the GRAX datalake
    c. Click Save at the bottom of the page
  7. Towards the bottom of the page is the section to set a default field value for fields on this object. Select this option if you want all records being restored to the destination environment to have a specific field value when restoring.
    a. Select the field value
    b. Select the value for the field that you would set
    c. Click Save

Viewing the restore mapping section with restore options


Default Field Value

For some objects within Salesforce, such as Orders or Contracts, records cannot be created with a Status of Activated. In this scenario, you could create the Order records and map the Status field to a custom field, while setting the default "Status" field to a value of Draft so that the record could be created. A subsequent update to the Order record to set the Status to the 'true' status held in your custom field would then be needed.


How Are Field Mappings Saved?

The field mappings are saved per object and are saved as global settings for all users. Before doing a restore, be sure to check the field mappings before restoring records.


How are Field Mappings Applied?

Any time you do a restore, GRAX will look across all objects being restored and apply any field mappings it finds for any of the objects.

Record-Level Restore

In addition to using the Search tab to find and restore records, you can also embed components onto your record detail pages which effectively will allow for the same behavior, except the view will be pre-filtered for the current record you are navigated to. So for example you could put the Search/Restore component on your Account Lightning Page, and that would allow you to select records child to Account, retrieve those results and even restore.


Salesforce Classic vs. Lightning

These instructions assume use of Salesforce Lightning. Restoring of records will also work in Salesforce Classic.


  1. Go to your Salesforce environment where you have installed the GRAX Application
  2. Go the page where you would like to update the page layout and select the gear in the top right corner and then Edit Page
  3. Click on the list of tabs and click Add tab and give it an appropriate name
    a. Our recommendation is to name the tab “Restore”
  4. Click on the tab and from the left drag on Lightning Component Visualforce
  5. Set the options as below:
    a. Visualforce Page Name: Grax Restore
    b. Height: We recommend 700, but use your discretion
  6. Click Save and make sure that the page has been “Activated”
  7. You should now see a tab for “Restore”

Adding a 'Restore' tab and the GRAX Restore Visualforce page to an Account's Lightning page.

Restoring a Child Record

  1. Proceed to the parent record in Salesforce.
    a. For example, go the Account record where you want to restore a child record
  2. Click on the tab Restore. If the tab Restore does not exist, confirm that the steps in the previous section were completed successfully.
  3. Select the Salesforce object that you would like to restore from
  4. Select the necessary fields from this object which you want to display
  5. Click the button Retrieve
  6. Depending on the user’s permissions, and the assigned permission set, the user will see either or both of these options:
    a. "Preview" icon: When clicked, the user is able to view this record which has been archived but is NOT able to restore it into Salesforce.
    b. "Restore" icon: When clicked, the user is able to restore this record which has been archived, and this will open the record in “edit” mode, and then once saved, the record will be re-created in Salesforce.

Bringing up a list of all child 'meter reading' records for an Account. We can preview the record and decide to restore.


Restore Attachment(s) - API Call

Note: The user will also have the ability to restore attachments related to this record which have been archived. This will consume 1 API Call per attachment.