What users see when trying to restore [Object]History.

If you're reading this doc, you've probably seen that you can't restore [Object]History (e.g. AccountHistory, CaseHistory, LeadHistory, OrderHistory, etc.) from a Gearset backup run. This is due to some limitations in how this record type is treated by Salesforce's SOAP API - one of the main tools we use for data backup.

This doc explains why you're unable to restore [Object]History records.

What are [Object]History records, and how do they behave in Salesforce?

In Salesforce you can enable field history tracking on your custom objects, and on most of your standard objects. When enabled, Salesforce tracks field value changes on that record. It's useful for giving a history of changes over time. In this example, you can see the history on an Account record:

You might expect this history to be stored on the record in question - if I make changes to an Account record, I expect the history will be stored on that record.

However, this isn't the case. Every time Salesforce detects a field value change, a new record is created. This record is not an [Account] record; it's an [Account]History record. This record stores the information you see in the screenshot above: date and time of the field value change, name of field changed, user making the change, original field value, and new field value. Behind the scenes, it also stores the RecordID for the [Account] record to which the [Account]History record belongs.

Therefore, if I choose to back up my Account records and their related histories, I'm actually backing up two record types: Account, and AccountHistory.

What's the importance of the SOAP API, when thinking about [Object]History records?

Salesforce provide the SOAP API to allow external applications such as Gearset to create, retrieve, update or delete data records. When Gearset uses this API, it makes "calls" to Salesforce.

For your custom objects and most of the standard objects (such as Account), Gearset can make a wide range of calls: create(), delete(), describeLayout(), describeSObjects(), getDeleted(), getUpdated(), merge(), query(), retrieve(), search(), undelete(), update(), upsert().

Broadly speaking, these calls can be grouped into two different categories:

  • "Fetch calls" will enable Gearset to retrieve your records, and check for deleted/ changed/ new records. Examples include getDeleted() and retrieve()
  • "Modify calls" allow Gearset to make changes to your record database. In the context of Gearset backup, we'll use these calls when you want to make a restore/ rollback a changed record. Examples of this call type include create() and upsert()

For [Object]History, the SOAP API only supports calls of the "fetch" nature: describeSObjects(), getDeleted(), getUpdated(), query(), retrieve(). We can't make any "modify calls", so Gearset can't change the database in any way.

What can I do with Gearset?

You'll still be able to back up your [Object]History records with Gearset, as Salesforce allows calls of the initial "fetch" nature. You can browse changes happening to the [Object]History database in the typical way, from your backup UI. But, you won't be able to restore from your backup, as the SOAP API doesn't allow it.

Note: [Object]History is excluded from the default backup filter - you can choose to include it when creating/ editing a backup job:

It's useful to know that you can download [Object]History records as a .csv file from any backup run. While restoring [Object]History to Salesforce isn't possible, it is reassuring that Gearset will allow you to access these histories, even if they were deleted from Salesforce.

Download your data records from a backup run

.csv downloaded via Gearset, showing AccountHistory records. These Account histories are the same records as shown in the Salesforce UI screenshot, near the top of this doc

Did this answer your question?