Restore

Introduction

There are 2 main ways to restore data with GRAX:

Point-in-Time Restore allows you to update existing Salesforce records back to a selected point in time, and additionally select which specific fields you want to roll back for the chosen records.

Alternatively, GRAX Restore, the focus of this guide, allows you to restore any archived or deleted records along with any child objects that you choose. This gives you the ability to visualize the entire hierarchy graph of records. Since this restore only inserts one object at a time back into Salesforce, it gives you the flexibility to insert one or more records for an object, address any validations or other issues that come up, and then decide which child object to insert next. Let's walk through how this works.

How to Seed a Restore

There are 3 main places from which you can kick off a GRAX Restore:

GRAX Record Page

You can arrive at the GRAX Record View via several different avenues, whether it be clicking into a record via the Execution viewer, or doing basic or advanced searches to find a specific record. Once you are on a record page, you can see a Restore button if GRAX has identified the record as either deleted or archived. Clicking this button launches the restore flow for this specific record (along with building the entire hierarchy beneath the record in question, in case you end up wanting to restore children in subsequent single object restore jobs; don't worry we'll take a look exactly how this works in a bit).

Remember:

GRAX differentiates between a deleted record (manually deleted by user in Salesforce and captured by GRAX through automated delete tracking job) and an archived record (deleted via a GRAX archive job).

A Delete Source of grax indicates this record was captured as deleted via a GRAX archive job

A Delete Source of salesforce indicates this record was captured as deleted via GRAX Delete Tracking.

Archive Execution

If you go to the "Executions" tab and click into any Archive job, you should see a Restore button at the top of the page. Clicking this kicks off the restore flow, specifically for the top-level parent object.

Clicking Restore would bring you into the restore flow, allowing you to begin with a single object restore of Cases in this scenario since Case was the top-level object that we selected in our archive.

Advanced Search

If you perform an Advanced Search, and be sure to filter by a Status of archived or deleted, then the search results offer a Restore button as well.

Filter your search by archived or deleted records, and you can see a restore button appear when you check off 1 or more records in the results view.

How to Perform a Restore

Now that we've seen the different ways to launch a restore, let's take a look at what the process looks like when restoring data. We'll take a look at a couple of sample scenarios to make this real and convey the different considerations.

Restore a Single Case and Child Objects

In the archive execution example above, you can see we've archived 4 cases. Let's navigate to one of those Cases and see what we notice.

We can see on the record view page, there is a Restore button available. We can also easily navigate the hierarchy and drill into specific children if we wanted.

When you click Restore, GRAX begins taking a snapshot of the entire hierarchy for this Case: every record on every object below the Case that is stored in GRAX. Typically this only takes a few seconds since we're only talking about 1 Case. But as we'll see later, if you tried to restore 1000 Cases, for example, GRAX would load the full hierarchy of all 1000 cases; this can take some time but don't worry you won't have to wait and watch as you'll be able to navigate away and come back when the processing of the hierarchy snapshot is done.

GRAX has successfully loaded the Case and all its children. You can click any object node to explore the hierarchy, though as you'll see this specific restore job is only for the Case.

I can click on an individual node in the hierarchy to see only the records for that object, and also then have the ability to Download a CSV of the IDs.

Skipped Records

You'll notice that all the other objects/records (besides Case) are greyed out and Skipped. This is because this is a single object restore, as you'll see. Each restore execution is only for 1 object. The entire hierarchy is captured here so that you can do multiple single object restore executions to bring back just a part of the hierarchy or the entire hierarchy if you need.

You may also see a record tagged as Skipped for other reasons, for example Salesforce may not allow insertion of it. You'll see this with certain FeedItems that Salesforce auto-creates and doesn't allow you to insert.

We can use this restore preview page to confirm the records we want to restore are indeed here, and also start planning for future restores based on this hierarchy snapshot. Once we're confident, we can click Restore.

Once you confirm and execute the restore, you're brought to the Restore Execution page. This page gives you a real-time update of the restore job.

We can see the 1 Case we wanted to restore is in progress.

Here are the various Restore Statuses you may see:

We can see that our single object restore of the single case has completed.

Now if we navigate to the Case record page, we'll see the new Salesforce ID and have the ability to view this record directly in Salesforce, but we can also use the version viewer to explore all versions, including the older archived version of this Case which had a different Salesforce ID. Pretty neat.

But what if we now want to restore all the Case Comments that were related to this Case? Well let's go back to the restore execution page.

After we saw our Case restore complete, we can click on another node such as Case Comment and launch another restore for ALL the Case Comments related to the Case.

We've launched another restore execution that, as we can see, restores 2 Case Comments and link them to the Case that was just previously restored.

The restore execution for CaseComment has completed and we can see both records were Successful.

We can continue rinsing and repeating for any other objects that are in the hierarchy snapshot. While this is a small sample size, you can see how flexible and powerful this can be to bring deleted or archived data back into Salesforce, along with the child records.

Restore Multiple Cases and Child Objects

Now that we've seen how to restore a single case that was part of our archive, along with its child objects, let's take a quick look at how to do essentially the same restore process but for multiple cases.

Let's first do an Advanced Search of all archived cases that were recently created. We see the 4 Cases that were part of our archive job. We'll go ahead and select a few of them and click Restore.

The restore preview flow launched and loads a snapshot of the hierarchy for the 3 selected cases. We can explore the hierarchy and when we're ready click Restore to kick off the restore of the 3 cases.

The 3 cases were successfully restored. We can now click into other child objects and launch restore executions for them as needed.

What is the correct order of objects to restore?

In the example above, we knew we wanted to start by restoring Cases, and then use the hierarchy snapshot to restore one child object at a time after that. But which object should we pick and in which order? That is a question that each administrator performing the restore needs to answer based on their unique Salesforce schema and business needs. The restore is a simple insert of data so if it can be inserted and the parent records already exist in Salesforce, it should succeed. For example, you won't restore Level 2 children before restoring Level 1 because most likely those Level 1 parents have to be restored and exist in Salesforce before the Level 2 children can be attempted.

Restore Options

The following options are available when you create a new restore:

• Overrides: This contains a list of fields that GRAX should override when creating new records, which is helpful to avoid some validation and consistency checks.

  For example, if you're trying to restore a record that has a picklist field value that no longer exists, Salesforce may reject it with a validation error. If the field is not required, you can tell GRAX to drop it by setting an override without value. Otherwise you can specify which value GRAX should use when creating new records of the given object.

• Skip Objects: This is a list of objects that GRAX should not attempt to restore in this job. It's useful to quickly ignore records that may be hard or impossible to recreate given validation, triggers and other constraints in your organization.

Additionally, in the Settings page there are global settings that apply to every restore:

• ContentDocumentLink "Share Type" Handling: This specifies the permission granted to the owner of the shared file in a library.

  In order to preserve the original permission granted at the time the file was deleted, the GRAX Integration User needs the "Library Manager" permission.

  If that cannot be granted, or if you don't have strict needs to preserve the original permission, you can set a global override here to always have ShareType set to V, which means the user "can explicitly view but not edit the shared file."

• Ignore objects: This holds a list of objects that GRAX skips, both while archiving and restoring data.

  For restores, this is basically a global list of objects to be skipped. It's helpful to track objects that have been deprecated or sunset in your organization, so you don't have to consider them during every restore job.

Restore Tab

You can find a list of all restore executions by using the Restore tab. Let's take a look at how this overview tab is organized. At the very top of the page, you'll see any pending or ready restores. As mentioned previously in this guide, it can sometimes take a longer time to load the entire hierarchy for a large set of data. Rather than waiting while it loads, you'll see a message that says you're able to navigate away and return to the Restore tab at a later tab and kick off the restore when it's ready.

Below this you'll see a list of all in progress or completed restores.

In this example, we can see we have 1 restore execution that is pending. This means GRAX is still loading the hierarchy snapshot for all the data. We also have 1 restore that is ready. This means the records have finished loading and you're free to go into the restore and kick it off.

Notes Restoring Files

When we refer to "Files" here we are referring to the interconnections between ContentDocument, ContentVersion, and ContentDocumentLink. GRAX automatically backs up all three of these objects when you do a File backup or an archive. But when restoring this data, there are plenty of Salesforce rules and limitations to be aware of. Here is the best way to go about restoring these Content objects, given that you'll need to do a series of single object restore executions:

1. First, select the ContentDocument node in the hierarchy graph. Even though Salesforce doesn't actually support API inserts of the ContentDocument object, this is the object GRAX uses in the interface to represent "Files."

2. Perform your restore of the ContentDocuments in question. When you kick off this restore, what's really happening is that GRAX is inserting a new ContentVersion record (this object contains the actual file binary), and then Salesforce auto-creates the ContentDocument for the ContentVersion. The post-processing backup step within the restore captures the new IDs of both the ContentDocument and ContentVersion.

3. As this point you have inserted the File back into Salesforce. However, it technically is "orphaned" as it won't link to any records at this point. You need to restore the ContentDocumentLink records to establish the linkage between the ContentDocument and any other records (Account, Case, User, custom object etc). So from the restore execution page, select ContentDocumentLink and restore those records.

Common File Errors

Typically when restoring ContentDocumentLinks at this stage you may get an error such as:

code=INSUFFICIENT_ACCESS_OR_READONLY msg=Invalid sharing type I

This is relatively common due to the way Salesforce treats ContentDocumentLink sharing. The ContentDocumentLink may have been backed up with a certain Sharing Type but that Sharing Type cannot be set when inserting the ContentDocumentLink. Reach out to GRAX if this becomes an issue.

Other errors you may see when restoring ContentDocumentLinks may be something like:

Document with ID: {Salesforce ID} is already linked with the entity with ID: {Salesforce ID}

Remember, when GRAX inserts the ContentVersion, Salesforce automatically creates a ContentDocument and also creates a ContentDocumentLink to share the ContentDocument with the restoring user (which is the API user specified in the GRAX Settings). So if you subsequently try to restore a ContentDocumentLink for that user, you predictably get an error saying it already exists, since Salesforce had auto-created it.