Migrating data from a Salesforce instance to an unrelated Salesforce instance the mapping between system tables can be complex and mapping rules are needed to control how records in a CopyStorm backup map to records in a target Salesforce.

This article review two types of mapping rules:

• Simple column value mapping rules.

• Complex mapping rules.

The Basics

All mapping rules provide a map of Ids in the CopyStorm backup to corresponding Ids in the target Salesforce.

For example:

• If a User record in CopyStorm has the same email address as a record in the target Salesforce, map the CopyStorm User.Id to the Salesforce User.Id.

Mapping rules are stored in a configuration file named “DefaultRecordMapRule.xml”, stored in any of the normal places for CopyStorm/Restore configuration files. It contains two types of supported entries:

• ColumnBasedBuilder — a mapping rule determining a match between two records based on the value of one or more columns.

• FunctionBasedBuilder — a mapping rule determining a match between two records based on user supplied Java code, using any technique to determine if records match.

The built-in DefaultRecordMapRule.xml looks like:

A Simple Column Value Mapping Rule is used when a CopyStorm and Salesforce record should be considered the same if one or more columns in the two records match. For example, the following rule indicates that two User records are the same if the records contain the same email address:

A rule indicating that Record Types match if they are for the same SObject and have the same Name is:

A Function Based Rule uses arbitrary Java code to build an Id mapping between CopyStorm records and Salesforce records. For example:

• The built-in Pricebook2 function rule ensures that the standard pricebook in the CopyStorm backup maps to the standard pricebook in the target Salesforce.

• The built-in Organization function rule ensures that the Salesforce Org Id in the CopyStorm backup maps to the Org Id of the target Salesforce.

There are two steps required to add a new Function Based Rule to CopyStorm/Restore:

1. Write a Java class implementing the rule and store the implementation in a jar within the “lib” sub-directory of the CopyStorm/Restore installation.

2. Add a “FunctionBasedBuilder” XML entry to the “DefaultRecordMapRuleBuilder.xml” file.

For example, this is the function based rule for Organization built into CopyStorm/Restore:

The Revert Pending tool undoes operations that set previously inserted or updated records to a pending state. This tool will change the state of records from Pending back to Inserted or Updated. The use case for this tool is:

• I accidentally reset a group of records to Pending and need to undo the change.

This tool only works on records where both the Original Id and Restored Id are non-blank (i.e. records that have previously been Inserted or Updated).

There is one decision to make when using this tool:

• What records should be reverted from Pending back to Inserted or Updated?

Release Date: 17-Apr-2024

This is a feature, bug fix, and Salesforce API version upgrade release. As always, existing CopyStorm configuration files are backwards compatible.

Patch Levels

Salesforce API Update

This release updates CopyStorm/Restore to use Salesforce API version 59.

Off-Database Partitions

This release introduces CopyStorm/Restore support for Folder and S3 data partitions. With this update, CopyStorm/Restore can recover field data stored in a local Folder or in S3.

The “Resume Restore” popup has been updates with a “Retry Failures” checkbox. If selected, this checkbox will cause CopyStorm/Restore to mark all Skipped records as Pending before proceeding to insert or update the pending records.

CopyStorm/Restore Flow management has been updated to query Salesforce for the active version of Flows selected on the “Advanced” tab. If there is an active version, the active version will be disabled / re-enabled by CopyStorm/Restore.

• Multi-Lingual Knowledge Restore Fixes.

  • Resolved issues preventing multi-lingual Knowledge Articles from being restored.

• Filenames with Colons.

  • Resolved an issue preventing Files and Attachments with the Colon “:” character in the filename from being recovered on Windows.

CopyStorm/Restore supports the ability to restore Salesforce data directly from a Snowflake database. This allows organizations that use CopyStorm to archive Salesforce data into Snowflake (for analytics or storage) to also leverage that same data for recovery purposes.

When configured with a Snowflake connection, CopyStorm/Restore behaves similarly to how it would with a traditional relational database. All standard restore operations are supported as long as the data exists in Snowflake.

When to Use CopyStorm/Restore with Snowflake

• You’re already archiving Salesforce data to Snowflake with CopyStorm.

• You need a simple recovery option without setting up a second relational database.

• You don’t need , , or file attachment support.

• Metadata Restore – Metadata cannot be restored from Snowflake.

• Point-in-Time Restore / Snapshots – Snapshot data is not supported in Snowflake.

• CS:Govern Restore – CS:Govern is not available for Snowflake.

• Base64 / Binary Content – Snowflake does not support native CLOB or binary types in the required format. As a result, objects like Attachment & ContentVersion cannot be restored from Snowflake.

CopyStorm/Restore restores all or part of a Salesforce instance using a backup created by CopyStorm.

• CopyStorm provides peace of mind by keeping a hot backup of your production Salesforce instance in a local relational database.

• CopyStorm/Restore turns your low-cost sandbox instances into high value developer environments using your production backup data.

CopyStorm/Restore can also be used to restore small or large parts of your production database in an emergency, but no one wants an emergency! Just as important is CopyStorm/Restore’s ability to populate inexpensive Salesforce developer sandboxes with slices of your production data:

• CopyStorm/Restore can populate a sandbox with the type of data you need for a development project.

• CopyStorm/Restore can restore a sandbox to a known state multiple times per day.

• CopyStorm/Restore provides a low-cost way for Salesforce consultants to demonstrate new features using the customer’s production data WITHOUT touching the customer’s production Salesforce.

Developers and contractors are probably asking, “OK. I see how this would help me a lot. How much time do I have to invest in the tool?”.

Just a few minutes is all you need — watch this video for a demo:

A Salesforce backup is always a good idea. Using your Salesforce backup to super-charge your developer sandboxes is even better.

The Dependency Detail tab lists the order in which tables will be written to Salesforce, the referenced tables occurring later in the list of tables, and the original table dependencies from the Salesforce metadata.

This page contains similar content to the Restore Order Detail tab, including two additional columns.

The “All Required” column lists all tables that must be restored before the table in the second column.

The “All Nillable” column lists all tables that are referenced by nillable reference fields in the table in the second column.

Welcome to the CopyStorm/Restore Learning Center.

This area contains articles to help you quickly install and restore Salesforce data.

See the video below for a complete end-to-end example:

Related Articles

• CopyStorm/Restore Value

• Overview

CopyStorm/Restore restores all or part of a Salesforce instance using a backup created by CopyStorm.

This article outlines the complete process used to populate a Salesforce sandbox with production Salesforce data:

1. Create a backup of your production Salesforce instance using CopyStorm (or use an existing backup).

2. Open the CopyStorm/Restore application.

3. Enter Salesforce credentials for the instance to be restored.

4. Enter database credentials for the CopyStorm backup database.

5. Select the data that will be restored to the Salesforce instance.

6. Run the restore.

7. Save the CopyStorm/Restore configuration so you can reuse it later.

8. Use the restored Salesforce instance.

The most complicated part of this process is step #5 — selecting the data to be restored. However, this step is only as complex as your selection criteria. Examples of simple selection criteria that can be chosen with only a few button clicks include:

• Restore 1000 random Accounts along with any related Opportunities, Cases, and Contacts.

• Restore these specific Contacts along with any related Accounts and records from the custom table ABC__c.

• Restore the 500 largest Opportunities from the past 6 months along with any related Accounts and Contacts.

The following short video illustrates the entire CopyStorm/Restore process:

For examples of other types of CopyStorm/Restore scenarios, see the .

Salesforce records often contain references to other records. For example:

• Contact records contain a reference to an Account in their AccountId field.

• Nearly all records contain a reference to the Salesforce user who owns the record in an OwnerId field.

The Reference Fields portion of the Restore Set Editor defines the action which should be taken if a record references another record that is neither:

The following video demonstrates how to restore metadata to Salesforce with CopyStorm/Restore:

Restoring metadata using CopyStorm/Restore is a simple point-and-click process — this can be used to:

• Promote code, permissions, or other metadata changes from Sandbox environments to Production.

• Roll-back metadata to previous versions if metadata has been incorrectly updated in Production.

All versions that have been backed up with CopyStorm are available to restore, providing an easy way to undo changes to metadata or migrate metadata between environments. CopyStorm/Restore can upload or roll back changes to dozens of metadata types, including:

The Restore Plan tab provides insight into the decisions made to determine the order in which CopyStorm/Restore will find restore candidates and the order in which records will be inserted / updated in Salesforce. There are a number of subplans displayed as illustrated in this screenshot:

All plans are an accurate representation of what CopyStorm/Restore does during a restore except for the Candidate Scan Order. The Candidate Scan Order plan is a good representation but the implementation is a bit more complex in order to handle arbitrary direct and indirect circular relationships between tables.

• — lists the order in which tables will be written to Salesforce.

• — lists the order in which candidates for a restore will be found and is based on the rules set up in the Restore Editor tab.

CopyStorm/Restore makes populating a Developer Sandbox with production data a painless operation. This article provides a guide for how to do this for your operation.

• A CopyStorm backup of your production Salesforce data.

• A Salesforce developer Sandbox.

This step will determine the type and volume of data that will be restored to the Sandbox. This step is both important and non-optional due to fairly severe size restrictions on Developer Sandboxes. It is highly unlikely that you will be able to import your entire production data set.

The choice of what types of records to restore depends on what you plan to do with the Sandbox. Records are often selected based on criteria like:

Parameters in this tab are less likely to be configured by the average user. They include:

Release Date: 5-Aug-2025

This is a feature, bug fix, and Salesforce API version upgrade release. As always, existing CopyStorm/Restore configuration files are backwards compatible.

This release updates CopyStorm/Restore to use Salesforce API version 64.

The Overrides tab supports adding and removing relationships between tables, and is an essential tool when Salesforce metadata contains inaccuracies or ambiguities. In practice, options on this page should not be changed unless instructed to by Capstorm support.

Most of the overrides necessary are probably already built into CopyStorm/Restore and you will not need any additional overrides.

The Salesforce Asset table showcases the need for overrides in order to build a good restore plan. The Asset table’s metadata claims that both of the ContactId and AccountId columns are nillable. Though technically true, it is also true that both Account and Contact must be restored before asset because the Asset table does not allow both Asset.ContactId and Asset.AccountId to be null. CopyStorm/Restore forces the correct order for restoration by overriding the relationships between Asset/Contact and Asset/Account to be required for the purposes of deciding the order in which tables are restored.

If this was done using the GUI, the entry would have:

• A Rule Type of Forced

The Set Records to Skipped tool directly sets the status of records to Skipped, causing CopyStorm/Restore to never attempt to restore the records. This is useful in a number of cases where records are identified in the candidate scan, but:

• It is known that the records will have problems if they are restored, but the record scanning results need to be kept.

• They are being held back from the current restore operation in preparation for being restored later.

The following screenshot shows available options on the Set Records to Skipped dialog:

A handful of Salesforce tables can be children of many other types of tables. Good examples include Attachments and Notes.

If you want to include the Attachments for all selected tables, one way is to open the restore rule for each table and include Attachments as a related list. Another quicker way is to open the Attachments editor and quickly select all possible parents using a GUI extension that only appears on tables like Attachments.

On the screen shot, Attachments for Contacts, Leads, etc. can be included in the restore set simply by checking the box next to the parent table name. Though this action is equivalent to adding Attachments as a related list, you will find this technique must faster for larger restore sets.

The Restore Order tab lists the order in which tables will be inserted / updated into Salesforce.

The order is determined using:

• The metadata from Salesforce to determine nearly all relationships.

• Additional configuration information in CopyStorm/Restore.

  • This is used to supplement inaccurate or incomplete Salesforce metadata.

CopyStorm/Restore will perform parent/child record analysis much faster if the CopyStorm database foreign keys are fully indexed.

To create the necessary indexes, check the on CopyStorm’s Configuration tab and rerun CopyStorm.

CopyStorm/Restore will still work without indexes but the analysis required to determine the order in which records must be restored will be much slower. For databases with millions of rows the performance is likely to be unbearable. This is because CopyStorm/Restore needs to do a lot of table scans by running queries like:

• SELECT id FROM Contact WHERE accountId IN (….)

These will cause the entire Contact table to be scanned (an Order(n) operation). After creating the indexes, each lookup is an Order(1) operation (e.g. 1000s of times faster).

The Show Skipped Reasons tool displays the reason(s) why CopyStorm/Restore failed to restore records.

Skipped records are organized using two parameters:

• Category — the general type of reason a record was skipped.

  • Most reasons use the category “Default” but some, like Lead, may use the category “Unsupported”.

The Migration Setup tab contains tools which are useful when migrating data to a Salesforce instance unrelated to the Salesforce instance used to create the CopyStorm backup.

This is useful when trying to perform tasks like:

• Mapping Users in a CopyStorm backup to users in the target Salesforce. In this case, Salesforce Ids will not work due to being unique to a Production or Sandbox instance’s setup. The Record Mapping Rule tool on this page supports implementing and establishing rules that CopyStorm/Restore will use to map users from the CopyStorm backup to users in the target Salesforce.

• Maintaining Salesforce Ids in a CopyStorm backup when creating data in the target Salesforce. In this case, Salesforce Ids will be regenerated when data is inserted. The Original Record Id Rule tool on this page supports creating and populating a new custom field to maintain the source CopyStorm database Id values.

The Candidate Scan Order tab lists the order in which Restore Set Editor rules will be traversed to find candidates to be restored.

Scanning for candidate records is a difficult problem due to direct and indirect circular relationship loops in Salesforce. For those of a graph theory bent, the problem of finding candidate records is a classic NP-Complete graph traversal problem in the same category as “The Traveling Salesman Problem” and finding minimal spanning ring systems in chemistry. Like all problems in this class, the search path is difficult to represent exactly in a linear set of steps. However, the plan displayed by CopyStorm/Restore is an honest representation of the search plan even thought the actual algorithm used by the search is a bit more complex.

There are a few core operations in a candidate scan:

• A “Find Records in Table” step searches for records within the table. In the plan below, the “Find records in Account” is likely running a SQL statement against the Account table.

CopyStorm/Restore automatically restores deleted records for all record selectors except for “All” and “Random”. To restore deleted records with these selectors, check the “Include Deleted Records” checkbox.

In a CopyStorm backup a record is deleted if the “IsDeleted” column is set to true. There is nothing special about the “IsDeleted” column — it is a normal column Salesforce uses to indicate that a record has been deleted.

The Global Parameters editor is used to specify:

• Parameters that apply to every table.

• Parameters that apply to the overall restore process.

• Parameters that are table specific, usually because of a Salesforce restriction.

The Restore Order Detail tab lists the order in which tables will be written to Salesforce according to the list specified in the Restore Order tab.

The following examples reference the screenshot below.

If a table name appeared in the Required Prerequisites column for Account it means that CopyStorm/Restore’s table scanning algorithm decided to write Account records to Salesforce even though the Account table contains a non-nillable reference column referencing a table later in the list of tables to be restored. In practice, this should never happen in a plan built by CopyStorm/Restore. However, if it does, this plan will show the issue and allow overriding Salesforce dependencies to fix the problem.

If a table name appeared in the Nillable Prerequisites column for Account it means that CopyStorm/Restore’s table scanning algorithm decided to write Account records to Salesforce when the Account table had a nillable column referencing a table later in the list of tables to be restored. This condition happens fairly frequently in Salesforce, and CopyStorm/Restore attempts to reduce the impact on restoration performance by optimizing table ordering. This condition is not an error but means that CopyStorm/Restore will patch up nillable reference fields in a second pass, after the records have been restored.

For most Salesforce metadata objects there are two restore type options.

• Complete: Restore the a complete backup of the object to Salesforce.

• Expert: Modify the raw definition of the object manually before deploying to Salesforce.

All CopyStorm/Restore simple editors look and behave similar to the ApexPage example below. Note that the only modifiable parameter is the version.

Switching the restore type to Expert will change the display to the Expert Mode Editor. For additional help see the page.

The Custom Object editor is used to select the precise components of a standard or custom SObject that will be restored.

For a partial restore only particular elements of a Custom Object should be deployed. The following example will do a limited restore of several custom fields.

A complete restore will cause all properties of a Custom Object to be deployed.

An expert restore provides fine grained control at the Custom Object XML level. The initial XML can be:

• The XML corresponding to the current partial editor.

Getting Started With CopyStorm/Restore

Contains common recipes for the restoration of Salesforce data using CopyStorm/Restore. Included are a basic sandbox recipe, restoring Accounts with largest Opportunities, and restore Accounts limiting the number of Cases per Account. A discussion of issues surrounding a complete restore and recipe of a complete restore is also included.

Understanding CopyStorm/Restore

Provides information essential to understanding how CopyStorm/Restore restores records and complex relationships to a Salesforce database.

CopyStorm/Restore Tracker Database

Describes the internal structure and types of data stored in the CopyStorm/Restore Tracker Database.

There are a number of occasions that require table specific processing rules. This section describes how to augment the built-in table specific processing rules in CopyStorm/Restore.

The most common case requiring a table specific rule is a need to limit the number of records sent to Salesforce in a single batch. The default value, 200, may be too large for specific tables because of complex INSERT / UPDATE triggers causing the “Too Many DML Statements” error to be thrown by Salesforce.

CopyStorm/Restore supports overriding or extending the default table processing rules by editing a file named “TableRuleRegistry.xml” in a subdirectory “config” of the root CopyStorm/Restore directory. By default, CopyStorm/Restore includes a template TableRuleRegistry.xml with a large block comment explaining usage.

Several common overrides are included below.

Limit All Salesforce Writes to Ten Records at a Time

The following sample TableRuleRegistry.xml file will cause CopyStorm/Restore to limit all writes to Salesforce to ten or fewer records:

<TableRules>
    <TableRule name="default" restoreBatchSize="20" />
</TableRules>

Limit All Contract Record Writes to Five at a Time

The following sample TableRuleRegistry.xml file will cause CopyStorm/Restore to limit all inserts / updates to the Case table to five or fewer records.

Though a Partial or Complete restore of a meta data element usually works, sometimes it is necessary to edit the raw XML that will be deployed to Salesforce. The Export Mode restore type provides this feature plus a few others.

• The raw data for the current partial restore, any backup in Capstorm, or the current Salesforce definition can be loaded and edited.

• Differences between what will be deployed can be quickly compared with the current partial restore, any backup in Capstorm, or the current Salesforce definition.

• Finding all occurrences of a pattern can be quickly performed.

Note that in Export mode, the raw data to deploy for an object is stored in the copyStormRestore file as part of the restore session configuration.

To restore a meta data object using the Export mode, simply choose Expert from the restore type pull-down menu.

The metadata to load into the left or right panels is selected using two different pulldown menus.

• The “Base Version” pulldown loads metadata into the editor on the left.

• The “Compare With Version” pulldown loads metadata into the comparison viewer on the right.

You will see several types of options in the pulldown menu.

The following screen shots illustrate how differences are displayed when the metadata on the left and right differ. For the example an ApexTrigger metadata objects was selected.

There two techniques for searching metadata.

• Differences will be calculated automatically and can be systematically walked thru using arrow control on the right.

• Specific text can be found by entering a regular expression in the Find parameter. These, too, can be systematically walked thru using arrow controls on the right.

Though CopyStorm/Restore provides good performance with its default settings, there are a few best practices to achieve optimal performance.

Index Your CopyStorm Database

To determine which records should be restored, CopyStorm/Restore performs a lot of reference field lookups on its CopyStorm database. If reference fields in the CopyStorm database are not indexed performance can be greatly impacted. To add all the necessary indexes to the CopyStorm database:

• On the CopyStorm Configuration tab make sure that the Create Indexes option is checked.

• Run CopyStorm to automatically create any missing indexes.

Store Your Tracker Database On a Local Disk

CopyStorm/Restore tracks the progress of a restore using a small-footprint database called a “Tracker Database”. This database is named on the Global Parameters tab and, by default, is stored in the directory $HOME/.capstorm/copyStormRestoreSets. If your home directory is not on a local disk, performance can be improved by changing the tracker database location to a location stored on local disk. For example

• If the tracker database is “fred” then it will be stored at:

  • $HOME/.capstorm/copyStormRestoreSets/fred.mv.db

• If the tracker database is C:\tmp\fred then it will be stored at C:\tmp\fred.mv.db

If the location already contains a tracker database, the pre-existing one will be used. If not, CopyStorm/Restore will automatically create a new one.

To upload data to Salesforce, CopyStorm/Restore uses 1-10 virtual data entry clerks (also called Salesforce Writers). Each Salesforce Writer enters data into Salesforce concurrently. In addition to the number of Salesforce Writers, the amount of work given to each writer in a single batch can be controlled to increase performance.

There are two parameters on the Global Parameters tab which control the level of parallelism:

• The “Default Max Per Update” parameter controls the amount of work given to a single Salesforce Writer.

  • This parameter defaults to 200 but a value of up to 600 can often improve performance.

• The “# Salesforce Writers” parameter controls the number of concurrent threads used to write to Salesforce.

Values for these parameters that work best for you depend on several factors:

• The speed of your internet connection to Salesforce. This is the most important factor.

• Salesforce limits the number of active update requests per Salesforce login for your entire Organization.

  • Running too many restores at the same time can cause this limit to be hit.

  • This issue has been observed when a customer was running three separate restores concurrently where each restore used the same Salesforce credentials and 10 concurrent threads.

In Capstorm’s test labs we typically use values of:

• Default Max Per Update = 400

• Salesforce Writers = 10

High parallelism parameters can, under certain circumstances, degrade restore performance. This has been observed when restoring to a table with a computed column involving aggregation of data from another table. If this happens:

• CopyStorm/Restore will still work but may have to make multiple restore requests for the same batch of records.

  • This happens internally in the program and the only visible effect is on restore performance.

• CopyStorm/Restore will automatically lower the level of parallelism on a table when it is causing restore performance issues.

• The level of parallelism can also be controlled for a specific table by setting table specific parameters on the Restore Set Editor tab.

CopyStorm/Restore uses a small footprint relational database (based on H2) to keep track of all restore activity. Like any database, it is possible (but rare) for this database to become corrupted. This article explains how to recover a corrupted H2 database.

Step 1: Create a New Directory and….

1. Copy the corrupted H2 database into the new directory.

2. Copy the file [CopyStormRestore Install Directory]/lib/h2*.jar into the new directory.

3. Open a command prompt and run java -cp h2*.jar org.h2.tools.Recover

4. The previous step will create a .txt file with the same name as your database. It may take a while to run and does not produce output.

java -cp h2*.jar org.h2.tools.RunScript -url "jdbc:h2:file:~/tmp/RecoveredTracker" -user root2 -password capstorm -script EMR-UAT-tracker.mv.txt -showResults

• The database in the -url parameter should not exist.

• The -user and -password parameter should NOT match a user in your corrupted database. root/capstorm are the defaults for a CopyStorm/Restore tracker database.

Of course, there is no guarantee that the recovery will work. Each case is likely to be unique. However, if the following tables are intact and have data there is a decent chance of recovery.

• RestoreConfig — this table must have values. It is used by CopyStorm/Restore to determine the version of the tracker database.

• RestoreTable — this table lists all Salesforce tables in the tracker and references to a unique tracking table for each Salesforce table. Do a SELECT * on this table.

• RestoreTableRecordReference

See this article for details about what is in a tracker database.

Release Date: 28-Apr-2026

This is a minor feature and bug fix release. As always, existing CopyStorm/Restore configuration files are backwards compatible.

Patch Levels

Important: Salesforce Username/Password Login Deprecated

Salesforce API version 65 deprecates the SOAP username/password login endpoint. Customers should migrate to an external client application configured with OAuth. Restore jobs using a login type that does not support API 65 will automatically fall back to API 64, and an exception will be logged at the start of each job as a reminder to migrate.

This exception can not be eliminated until OAuth authentication is used.

Salesforce API Version Fallback for Username/Password Logins

The "Fallback API Detected" error does not stop your jobs from running - it is informational, and indicates that CopyStorm/Restore is not able to use the most recent Salesforce API features. The error will be resolved when updating to JWT (or other OAuth) authentication.

Please reference .

This release includes an upgrade to the H2 database used for restore tracking. Existing tracker databases are not compatible with this version.

This release updates CopyStorm to use Salesforce API version 65.

The target Salesforce organization is now displayed more prominently before a Restore job begins, reducing the risk of restoring to an unintended org.

Overflow Snapshots are no longer included by default during Candidate Scanning. This change improves scan performance for most restore workflows.

Improved the error message displayed when a ContentVersion restore fails on an unsupported database type (e.g. Snowflake).

Fixed an issue where the "Trace Mode" configuration option was not applied correctly during restore execution.

Resolved an issue where tracker database operations could fail for objects with unusually long names.

The Salesforce API version is now logged at the start of each Restore job to aid in troubleshooting.

Fixed an issue where the "Rich Text Fields" configuration tab incorrectly included formula fields that contain hyperlinks.

When creating data in Salesforce, autonumber columns are given new values automatically. To override this behavior and restore historical autonumber column data with CopyStorm/Restore, there are two approaches that can be taken:

1: Restoring Data to Custom Autonumber Fields

Uploading data to a custom autonumber field requires that autonumber generation be disabled during the restore. It is always best practice to perform this task during a maintenance window to prevent users from creating data while autonumber generation is disabled.

To disable autonumber generation for a custom field while restoring data with CopyStorm/Restore:

1. Go to the custom field in the Object Editor.

2. Record the field information, including the next number in the sequence and the display format.

3. Modify the field type, setting it to Text.

   • This will disable autonumber generation during the restore.

4. Upload the data with CopyStorm/Restore.

5. Modify the field type, changing it back to an autonumber.

   • This will re-enable autonumber generation.

   • Use the field information from Step 2 — potentially with a different sequence number depending on the data being uploaded.

Salesforce’s standard autonumber fields (i.e. Case Number) come with an additional restriction — their field type cannot be modified. Uploading data to a standard autonumber field requires that the standard field be replaced with a copy used in place of the standard field.

To set up a copy of the standard field that can be used with CopyStorm/Restore:

1. Create a new custom field to hold the autonumber data.

2. Create an insert trigger to populate the new custom field:

   • If there is no data in the custom field, populate it by copying the standard autonumber field.

   • If there is data in the custom field, keep the data and don’t overwrite the field content.

After Salesforce is configured with a field to use when restoring the autonumber data, the custom field can be uploaded just like any other field in Salesforce — there are no special configurations needed during the restore process!

Parameters for controlling the suppression of common record skipping reasons – for example: Child records may be skipped when their parent record(s) are skipped – this skipped reason is typically suppressed because it is a side effect of the parent being skipped.

Commonly used parameters that affect the complete restoration process.

Clicking on the Restore Tab’s “Re-scan Candidates” button will display a dialog to configure parameters for the re-scan operation:

Pressing the “Start Operation” button will cause CopyStorm/Restore to identify any new records in the CopyStorm database that match the current configuration in the Restore Set Editor. All records that are identified will be added to the Tracker Database – allowing them to be restored by CopyStorm/Restore.

The default settings in this popup will cause all tables, records, and relationships to be rescanned. This will ensure that any changes in the CopyStorm database or Restore Set Editor are reflected in the Tracker Database.

There are three checkboxes that can be used to limit the amount of data scanned:

1. Rescan All Record Relationship Dependencies (if false, only new records are scanned)

   • If this checkbox is checked, all records’ related list and reference field rules will be scanned.

   • If this checkbox is unchecked, only newly identified records’ related list and reference field rules will be scanned.

2. Mark Updates as Pending (if false, only new records will be marked as pending)

   • If this checkbox is checked, both new records and records that have been updated in the CopyStorm database will be set to Pending in the CopyStorm/Restore Tracker (and subsequently inserted or updated in Salesforce).

   • If this checkbox is unchecked, only new records will be set to Pending in the CopyStorm/Restore Tracker.

3. Select Specific Table Rules to Include (by default all are included)

   • If this checkbox is checked, CopyStorm/Restore will only scan for new records in the indicated tables.

   • If this checkbox is unchecked, CopyStorm/Restore will scan for new records in all tables configured in the Restore Set Editor tab.

If the Select Specific Table Rules to Include checkbox is checked, a table selector will appear to allow specific table selection:

The “Related Lists” editor determines which records from related lists will be restored for each record. For example, when restoring Account the related lists Contacts, Cases, and Opportunities will usually be available.

To restore a related list click on the check box next to the name.

In the following screen shot the related lists Assets, Cases, Contacts, and Opportunities were selected for the Account table. This will cause CopyStorm/Restore to restore all Asset, Case, Contact, and Opportunity records related to selected Account records. Note that the superscript on each related list indicates the SalesForce Table and Column associated with the list.

• Related lists can be selected to any level. Example: Account->Contact->Attachments.

• As related lists are selected, they will automatically be marked as checked in the master table list on the left.

The control buttons at the top are often quite important and can be used to:

• Expand/Collapse the tree of related lists.

• Select all related lists (direct, grandchildren, great-grandchildren, .etc.) to any level.

• Deselect all related lists.

In the following screen shot, the account named Capstorm, LLC and all of its related lists were selected for a restore. The steps were:

• Set the Account filter to select just the Capstorm, LLC company.

• Click on the Select All button for related lists.

Are you curious about how many tables were actually selected? The answer is 60!

When restoring test datasets to developer sandboxes or other environments with limited data capacity, it can be useful to limit the total number of records that will be restored either in:

• Any single related list under any single record – for example, to ensure that no single Account will have more than the specified number of Contacts.

• A single table, regardless of how many related records are in the CopyStorm database, will be limited to the specified number of records.

In practice, it is unusual to restore absolutely every related list for a record because certain system tables are best excluded (since they are already populated). When the Select All button is clicked, checking the “Include System Tables” checkbox will give you the option of restore none, a few, or all related system tables.

In Salesforce, it is common to see attachments and files associated with EmailMessage records. The Salesforce API however has restrictions about linking ContentDocumentLink records to EmailMessage records over the API when the EmailMessage record status is not ‘Draft’ and produces an exception in this scenario. This information be found in the Salesforce Object Reference for EmailMessage here.

On the EmailMessage object however, there is a field called IsClientManaged that when true allows users to modify EmailMessage.ContentDocumentId sto link file attachments even when the Status of the EmailMessage is not set to ‘Draft’. As of the 10.64.3 GA release of CopyStorm/Restore, an additional parameter in the Restore Set Editor for EmailMessage can be selected to push EmailMessage records with IsClientManaged = true regardless of the value in the CopyStorm database.

NOTE: This behavior is disabled by default and must be enabled through the CopyStorm/Restore configuration file.

How to Push EmailMessage Records with IsClientManaged = true

Follow the below steps to push EmailMessage records with the IsClientManaged field set to ‘true’ for all records:

• Open CopyStorm/Restore and navigate to the Restore Set Editor tab

• Click on EmailMessage in the lefthand list of objects

• In the Select Records section of the EmailMessage Restore Rules find the Additional EmailMessage Parameters section and check “Set IsClientManaged”

Clicking on the Restore Tab’s “Continue Restore” button will display a dialog to configure parameters for the restore operation:

Clicking on the “Start Operation” button will cause CopyStorm/Restore to upload all Pending records from the Tracker Database into Salesforce – either resuming a previously cancelled restore job or augmenting a previous restore with all new candidates in the Tracker Database.

If any record(s) are being retried via the Tracker Database’s “Set to Pending” feature, their historical skip reason and exception information will be removed from the tracker prior to the restoration reattempt (if they fail to restore a second time, the most recent skip reason and exception will be recorded).

To delete the history of previously restore records and restart the restore from the beginning, update the “Reset Restore” dropdown:

• Do Not Reset – keep all Restore history.

• Reset Exception History – delete Exception logs before restoring records.

• Reset Restore History – delete all restore history and record maps before re-scanning for candidates and restarting the Restore.

To try to insert / update records that previously failed to Restore, check the “Retry Failures” checkbox. If this checkbox is checked:

• Mark all “Skipped” records in the Tracker as “Pending”.

• Try to Insert or Update all records that were changed from “Skipped” to “Pending”.

To limit the tables that CopyStorm/Restore will push to Salesforce, check the “Select Specific Table Rules to Include” checkbox. If this checkbox is:

• Unchecked, all pending candidates will be restored.

• Checked, only pending candidates from the selected tables will be restored.

Checking the “Select Specific Table Rules to Include” checkbox will display a table selector, allowing specific tables to be selected as candidates for restoration:

• Repair Reference Fields

  • This option will cause CopyStorm/Restore to update previously restored records with the latest Id mappings from the Tracker Database and Migration tabs.

  • This option should be used when performing incremental restores using the “Select Specific Table Rules to Include” option.

• Ignore Advanced Tab Rules

The Set to Pending tool resets the Track Database back to a “Pending” state, causing CopyStorm/Restore to attempt to restore the records again. This is useful in a number of cases:

• A validation caused records to be skipped during a previous restore. The validation rule was then disabled and the records should now be restored.

• Records were previously restored but the data in the CopyStorm backup has changed. Previously restore Salesforce data should be overwritten.

• Records in Salesforce were deleted by hand and should be re-restored without losing the tracker history.

The following screenshot shows available options on the Set to Pending dialog:

There are a few decisions to make when using this dialog:

1. Choose which records to reset to pending.

2. Choose which record statuses can be affected.

Default parameters will change all visible skipped records to a pending state.

• Records to Reset to Pending

  • “Visible”: Only change the status for records that are currently displayed in the Tracker Database table, taking filters into account.

  • “Table”: Change the status for all records in the currently selected table, do not take filters into account.

  • “Select Tables”: Change the status of one or more tables in the tracker.

The Profile Set editor provides fine grained control for the restore of a Salesforce Profile record.

Partial Restore

For a partial restore, specific sub-components of a Profile are selected for the restore. A partial restore is often used when migrating a Profile to a new environment where the original Profile contains entries related to objects/fields are not in the target Salesforce.

Complete Restore

A complete restore will cause all properties of a Profile to be deployed.

Expert Restore

An Expert restore provides fine control over the XML which is restored. See the Expert Mode Editor for details.

Restoring a Salesforce custom setting is a simple process once you understand:

• Each custom setting is kept in a Salesforce SObject where the sobject has a extra flag indicating that it is a Custom Setting.

A custom setting restore is a two step process.

Step 1: Restore the Custom Setting SObject

The first step is to restore the SObject.

• Goto the CopyStorm/Restore MetaData tab

• Search for the custom setting table in the list of CustomObjects.

• Restore the table.

After this step your target Salesforce will contain the custom setting but no values will be set for the setting.

This step restores the customer setting data using CopyStorm/Restore (just like any other table).

• Goto the Restore Set Editor Tab

• Select the table associated with the custom setting.

• Make sure the “All” record selected is active.

• Run the restore.

CopyStorm/Restore supports saving a restore set configuration in two formats:

• Plain-text XML.

• Encrypted text using 256-bit DES encryption.

Both formats allow saving Salesforce and database credentials — passwords are always encrypted. A CopyStorm/Restore session can be completely restored using the File / Open operation.

The “Save” dialog allows the selection of a directory and file name, as well as options to Encrypt and Save Passwords:

The plain-text XML version of the file is not intended to be edited by hand, as it is fairly complex. If problems arise from hand-editing a configuration file, Capstorm may not supply support.

The Notes Tab is useful for storing notes about a restore. The text is free-form and saved in the CopyStorm/Restore configuration file.

Advanced parameters for controlling how data is written to Salesforce.

The Deploy action (button) launches a dialog for initiating and monitoring a deployment to Salesforce. Deployments consist of three stages:

• Review/update the options controlling the deployment.

• Review the deployment plan.

• Run the deployment.

Generally the only step a user needs to do is click on the “Deploy” button.

Deployment Options

The Deployment Options tab controls how the deployment is executed.

The Deploy Plan tab lists a summary of all metadata objects that will be deployed. This is used as a final review prior to launching the deployment.

The Deploy Log tab shows the progress of the deployment as it happens and provides a way to cancel an active deployment.

During a deployment this tab may look like the following:

When the deployment is complete the log tab will show the final status of the deployment:

When Salesforce Knowledge is used in multiple languages, there are “master language” articles and “translations.” Salesforce has very strict rules about how these articles must be handled. The CopyStorm restore process is designed to follow these rules automatically to ensure a multilingual Knowledge Base is restored correctly

The Restore Order: Masters First

The most important rule is that for any article version, the master language article is always restored before its translations. CopyStorm’s process identifies the master article and ensures it is restored first.

For example, the restore will happen in this order:

1. First, it restores Version 5 of the English master article: “How to Reset Your Password.”

2. Next, it restores the translations of Version 5, such as “Cómo Restablecer su Contraseña” (Spanish) and “Wie Sie Ihr Passwort zurücksetzen” (German).

3. Finally, it promotes the master language and translations to Online or Archived, depending on the status of the article in the CopyStorm database.

This order is necessary because a translation cannot be correctly published in Salesforce until its master version already exists.

Salesforce has another rule: a translation cannot be published if its master article has a new Draft version in progress. CopyStorm’s smart sorting process handles this by making sure the current Online master version and its translations are restored before it tries to restore a new Draft of that same master article. This keeps the parent article in a stable Online state so its children translations can be published without errors.

Translations do not need to be archived one by one. Salesforce simplifies this process.

When a master language article is archived, Salesforce automatically archives all of its published translations at the same time.

CopyStorm’s restore process uses this behavior. The final “archiving” phase of the restore job focuses only on archiving the master articles. CopyStorm correctly sets the master article’s status to Archived and relies on Salesforce to then handle the connected translations.

By following these strict ordering and archiving rules, CopyStorm ensures that master articles and all their translations are restored with their relationships intact.

Release Date: 15-Sept-2023

This is a minor feature and bug fix release. As always, existing CopyStorm/Restore configuration files are backwards compatible.

Patch Levels

Add Email Deliverability Validation

This release introduces a feature to detect and warn if email deliverability is enabled in the target Salesforce org. CopyStorm/Restore can be configured to warn if email deliverability is enabled, halt the restore if email deliverability is enabled, or ignore email deliverability entirely.

Data restoration logic has been updated so that UNKNOWN_EXCEPTION errors will not cause the full CopyStorm/Restore job to terminate – instead, the impacted records will be marked with the UNKNOWN_EXCEPTION error and CopyStorm/Restore will continue with the rest of the recovery.

With this release, Tasks that are marked as Archived within Salesforce can be matched using the Multi-Column record match policy along with non-Archived Tasks.

The Permission Set editor provides fine grained control for the restore of a Salesforce permission set.

Warning: Restoring a Permission Set completely replaces its definition in Salesforce. Unlike Profile restores, Permission Set restores DO NOT incrementally change a Permission Set.

Partial Restore

For a partial restore, specific sub-components of a Permission Set are selected for the restore. A partial restore is typically used when migrating a Permission Set to a new environment where the original Permission Set contains entries related to objects/fields are not in the target Salesforce.

Complete Restore

A complete restore will cause all properties of a Permission Set to be deployed.

Expert Restore

An Expert restore provides fine control over the XML which is restored. See the Export Mode Editor for details.

While it is best practice to store Salesforce Reference Ids in Reference Fields, there are a handful of situations where a Reference Id may be stored in a Text field.

By default, CopyStorm/Restore will use Reference Field metadata to determine whether or not a field contains a Reference Id, and which table(s) the Id may reference. In cases where Reference Ids are stored in Text fields CopyStorm/Restore can be configured to treat the field as a Reference Field, which will cause CopyStorm/Restore to:

• Take the reference information into account when determining the table restore order.

• Use CopyStorm/Restore’s Old Id to New Id mapping to ensure referential integrity when uploading field values for the Text field.

To configure CopyStorm/Restore to treat a Text field as a Reference field:

1. Create a file [CopyStormRestore]/config/CopyForceMetadata.xml

2. Use the following template to populate the file:

This article discusses common reasons that may prevent records to restore using CopyStorm/Restore.

Triggers

Your Salesforce instance may have triggers that need to be disabled prior to restoring records. Here are a few examples:

• A BeforeUpdate trigger computes sales tax for a Quote. The error seen when restoring records is “TOO MANY SOQL STATEMENTS”.

• A BeforeInsert trigger does data validation on a specific field whose validation rules have changed over time. The error seen indicates that an INSERT or UPDATE failed.

Errors caused by triggers may be complex because a failure at a high level (e.g. Opportunity) may cause subsequent failures.

Inactive Price Books and Prices

CopyStorm/Restore’s default configuration will not restore Opportunity or Quote records referencing inactive price books or prices. To include these records you must explicitly enable the behavior on the Global Parameters tab.

You may see an error indicating that data from the backup is not valid for a restore. These are typically caused by numeric values with too many digits or email addresses in an invalid format, represent real errors in your source Salesforce database, and should be corrected.

This section explains the best practices for recovering and restoring Salesforce Knowledge base using CapStorm/Restore. Because Knowledge is a uniquely complex object with strict rules, these articles provide a detailed look at CapStorm’s specialized restore process.

Related Articles

• The Knowledge Article Restore Lifecycle — an overview of the three-phase process (Draft, Online, Archive) that CapStorm follows to safely restore Knowledge articles, including important considerations to know before starting.

• How CapStorm Handles Master Language and Translations — an explanation of the specific rules and automated processes CapStorm uses to correctly restore a multilingual Knowledge base, ensuring master articles and their translations are handled in the proper order.

• — a guide to the advanced settings available for Knowledge recovery, explaining what options like “One Version Per Push” do and the best-practice scenarios for using them.

There are a number of reasons that may cause CopyStorm/Restore to skip a record during restore. The most common include:

• The record references another record that is not in the CopyStorm database.

• The record references a record that failed to restore for another reason.

• The record is already in the target Salesforce and has exactly the same timestamp.

There are also a number of Salesforce table specific reasons that will cause a record to be skipped (i.e. operations Salesforce does not allow). For example,

• Activated Contracts cannot be written to Salesforce.

• Converted Leads cannot be written to Salesforce.

• Opportunity Line Items cannot be inserted if they reference an inactive price.

• Quotes cannot be inserted if they reference an inactive price book.

Normally, when a record is skipped the reason is stored as part of the tracker database (an exception to this rule is make for Converted Leads and Activated Contracts). When there is a reason in the tracker database it can be found by clicking on the “Status” of a record — the reason will be displayed in a popup dialog. If no popup dialog appears, CopyStorm/Restore did not record the reason the record was skipped.

There are a few options on the “Global Parameters” tab that can increase the number of skipped record reasons that are recorded. These options can be found under the “Skipped Record Reporting Options”. If you enable all options in this section, the maximum number of “skipped record reasons” will be recorded in the tracker database.

Release Date: 12-Jan-2024

This is a minor feature and bug fix release. As always, existing CopyStorm/Restore configuration files are backwards compatible.

Patch Levels

Add Support for CopyStorm Table Partitions

CopyStorm/Restore has been updated to support CopyStorm Table Partitions created by the CopyStorm/Medic Partition Editor tool. After Partitions are created in CopyStorm/Medic, CopyStorm/Restore will automatically query and restore fields from the correct partition(s).

To prevent chicken-and-egg issues in File recovery, the ContentDocumentId reference field on ContentVersion has been updated to always default to the “Set to Null” setting. Any previous configurations for this field will continue to be respected – and any changes to this reference field’s configuration will be respected.

The Record Mapping Rule tool is used to create rules telling CopyStorm/Restore how to map between records in the CopyStorm backup to records in the target Salesforce. This is very useful for migration in mapping Salesforce users and a variety of core Salesforce configuration records.

For example:

• Mapping Salesforce Users by their email address.

• Map Record Types based on record type (where the names are not the same in CopyStorm and the target Salesforce).

CopyStorm/Restore includes default mapping rules for a few common tables. However, these rules do nothing by default because no specific mappings are supplied.

Restoring proper record ownership when restoring historical data can be a complex operation for several reasons:

• By default, Salesforce does not permit an inactive user to be the owner of a record.

• When migrating data from another Salesforce instance, the record owner probably does not exist in the target Salesforce.

While discussing how to manage these issues, this article will also cover a related problem:

Each time CopyStorm, CopyStorm/Restore, or CopyStorm/Medic runs, it records job information and statistics into a set of history logging tables within the CopyStorm database. The History Tab supports viewing and exporting CopyStorm job history.

The History Tab consists of two sections — a top section used to search for past CopyStorm jobs and a bottom section displaying a one-line status for each job in the database.

When the “View…” column is clicked from the History tab, a dialog appears providing detailed job status. This dialog will open with the Overview tab which displays a list of the tables present in the restore set with metrics for the records that were restored, skipped, or encountered exceptions within each table.

• By clicking the “View…” link in the left-most column for any given table in the Overview list, you can view more detailed information about the restore operations carried out on the records within that table.

CopyStorm/Restore organizes tables into groups based on the probability of a table being directly selected for a restore. There are a number of groups predefined by CopyStorm/Restore:

The Original Record Id Rule tool is used to create a custom field in the target Salesforce and populate the new custom field with record Ids from the CopyStorm backup database. This is useful in a number of migration scenarios when the original Id of records being migrated must be maintained.

For example:

• The Original Id may be used after the migration to correlate data between the source and target orgs.

• Salesforce Id may be used as a key by an external system which must be able to access the original Salesforce Id.

Original Id field creation is enabled by checking the “Enable this Feature” checkbox. Available options include:

The Meta Data tab enables the restoration of Salesforce metadata with surgical precision.

This tab is divided into three sections:

• The Object Selector — add or remove a metadata object from the deployment set.

• The Object Editor — precisely select the properties of a metadata object that should be deployed.

• The Object Deployment Tools — deploy the selected metadata.

A CopyStorm/Restore can be opened, viewed, and manipulated independently of CopyStorm/Restore using the . The H2 Console is a web based tool built into the H2 which supports all of the regular SQL commands associated with any relational database. The launch script for the H2 Console is located in the same directory as CopyStorm/Restore and called:

• h2console.bat (windows)

• sh h2console.sh (Linux and Mac)

Note: IT IS IMPORTANT to start the H2 Console using this script if you intend to modify a tracker database using SQL. Otherwise your modifications will failed because required database triggers will not be found (the triggers are implemented in Java and loaded using the

Release Date: 19-Dec-2025

This is a minor feature and bug fix release. As always, existing CopyStorm/Restore configuration files are backwards compatible.

Java version 17 or higher is required for CopyStorm/Restore version 10.64.3. A supported Java environment is included with each Windows installation, however, Linux or Mac users should verify installed Java version prior to upgrading.

Parameters for controlling the level of parallelism and memory used when scanning the CopyStorm database for records to restore.

Before restoring Attachments with CopyStorm/Restore it may be useful to understand how Attachments are handled by Salesforce and how they are different from most tables. When a table in Salesforce contains a reference to another table it is almost always possible to know the type of table being referenced. For example, the Contact.AccountId field will always reference a record in the Account table. However, in the Attachment table, a number of reference fields are not so specific (e.g. Attachment.parentId) and can reference many built-in and all custom tables in Salesforce. This type of table is also known as “polymorphic” because they can “morph” into being a child of almost any type of table.

When restoring polymorphic table records, the best way to find the records is almost always to start with their parent table.

If this is a bit confusing, here is a specific example for restoring Attachments related to Accounts:

This informs CopyStorm/Restore to avoid inserting or updating Account records. The application will still find candidate records — this is necessary because the Attachments to be restored reference Accounts.

This informs CopyStorm/Restore that it should:

CopyStorm/Restore allows you to incrementally restore records to a Salesforce sandbox. This article will show you how.

If you do not want to know how CopyStorm/Restore works, this is the only section you need to read. The instructions are:

1. Open the configuration file used by CopyStorm/Restore during the original restore.

2. Go to the Restore Set Editor tab and modify or add rules that control which records should be restored.

3. Go to the Restore tab and click on the “Re-scan Candidates” button.

Release Date: 2025-Apr-01

This is a minor feature and bug fix release. As always, existing CopyStorm/Restore configuration files are backwards compatible.

The CopyStorm/Restore Record Lineage feature is specifically designed to maintain data record lineage. It keeps recovery information between backed-up and recovered versions of the same data within the CopyStorm database, ensuring that the relationship between data at different points in its lifecycle is preserved.

Release Date: 16-Dec-2024

This is a feature, bug fix, and Salesforce API version upgrade release. As always, existing CopyStorm/Restore configuration files are backwards compatible.

This release updates CopyStorm/Restore to use Salesforce API version 62.

CopyStorm/Restore’s Advanced Metadata Selector provides a way to identify Metadata that has been modified at a particular point in time. After selecting the point in time, CopyStorm/Restore will automatically identify the metadata items that were modified during the provided window.

The following dialog will appear:

Provided Parameters:

• Start Date (Optional): Metadata changes made after this date will be added to the Restore Set.

CopyStorm/Restore has the ability to transform data in the CopyStorm backup database prior to writing it to the target Salesforce. Built-in data transformers include:

• Scramble — replace each letter with a different letter, replace each number with a different number.

• Email Scrambler — build a new email address of the same size but with random letters & digits.

• Email Append Invalid — append “.invalid” to an email address.

• Asterisk — replace the source data with “******”.

• Random Dictionary Substitution — for Names, Countries, Cities, Streets…etc

• Lorem Ipsum — replace a block of text to the infamous “Lorem ipsum dolor sit amet, consectetur adipiscing…”

• Random Date/Time — replace a date or date/time with a random date or date/time within the same year.

Read more about built-in transformers in the

If the built-in transformers are insufficient for your needs the instructions in this article can be used to add a new transformer to CopyStorm/Restore. The approach described in this article is the same as what CopyStorm/Restore does internally.

To add a dictionary transformer that substitutes values from a provided list of values, you can create or update update the TransformerRegistry.xml file with a tag:

<Transformers> <Dictionary name=”My Transformer Name” file=”/path/to/a/file.txt”/>

This will add two new transformers:

• Random: My Transformer Name

• Uniform: My Transformer Name

These transformers will replace the input text with a value taken from the text file (one value per line). The Random transformer will replace each input value with a random line from the text file. The Uniform transformer will replace each input value with a line from the text file, always replacing the same input text with the same value from the text file.

The first step is to build a Java class implementing “com.capstorm.copystormrestore.transform.ITransformer”. The code below contains the implementation of the Asterisk transformer:

The parameters to the transform() method are:

The method must return the value to insert / update in Salesforce.

Once the class has been created, package it into a jar and put the jar into the “lib” subdirectory of the CopyStorm/Restore installation. CopyStorm/Restore will only find your class if it is installed in this directory.

For CopyStorm/Restore to discover a field transform it must be declared in a file named “TransformerRegistry.xml” and placed into a directory where CopyStorm/Restore looks for configuration files (for example, the “config” sub-directory of the CopyStormRestore installation).

The TransformerRegistry.xml file should look like the following:

Where:

• “name” is the value that will appear in the CopyStorm/Restore GUI.

• “class” is the full path to the class built in the first step.

To set up a build and test environment for a new transformer in Eclipse:

• Create a new Java project.

• Update the new project’s path to reference all jar files in the “lib” sub-directory of CopyStorm/Restore.

For other development environments, including building and testing on the command line, make sure that all the required Jars are on your Java class path.

If this is to much for your team send an email to and they will be happy to arrange a small service contract.

Snapshot Recovery is used to recover Salesforce data that is stored in a CopyStorm Snapshot. This is useful in a variety of recovery scenarios when the data or schema contained within the primary CopyStorm data set is insufficient to perform a historical data recovery.

For example:

1. A field was deleted in Salesforce and is no longer contained within the primary CopyStorm data set.

2. Salesforce records must be reverted to their state at a known point-in-time.

3. Salesforce records modified during a known window must be reverted to the state the records took at a known point-in-time.

To configure CopyStorm/Restore for Snapshot Recovery, select a Snapshot using the “Data Set” drop-down on the CopyStorm/Restore Main tab. Records from the selected Snapshot will be available for restoration.

Selecting a Snapshot will configure CopyStorm/Restore to recover records from the specified Snapshot.

After selecting a Snapshot, CopyStorm/Restore will display Point-In-Time Recovery Parameters near the top of the application. These parameters are used to recover record data from a specific time or interval:

More information about CopyStorm/Restore’s Point-In-Time Configuration can be found either later in this document or within the Point-In-Time configuration dialog:

Point-In-Time configuration is driven by the Point-In-Time strategy selected in the “Recover” drop-down:

• Most Recent: Recover the latest version of selected records.

• A Point In Time: Recover the version of selected records closest to the selected date / time.

• A Single Date: Recover records that were modified on a given date.

• Between Two Times: Recover records modified between to dates / times.

When the “Most Recent” Point-In-Time Strategy is used, CopyStorm/Restore will use the record filtering and relationship rules configured on the to find records within the selected Snapshot.

If there are multiple versions of a record within the Snapshot, the version with the most recent modification time will be restored to Salesforce.

When the “A Point-In-Time” Point-In-Time Strategy is used, CopyStorm/Restore will use the record filtering and relationship rules configured on the to find records within the selected Snapshot, only considering record versions modified prior to the provided date/time.

If there are multiple versions of a record within the Snapshot, the version with the most recent modification time (prior to the provided date/time) will be restored to Salesforce. If a record is in the Snapshot, but no version of the record has a modification time prior to the selected date / time, the record will not be restored.

This Point-In-Time Strategy is used to revert Salesforce records to the values that the records held on a specific day and time.

Available date/time formats include:

• dd-MMM-yy (19-May-1984)

• M/d/y (5/19/84)

• dd.MM.yy (19.5.1984)

• dd-MM-yy (19-5-84)

When the “A Single Date” Point-In-Time Strategy is used, CopyStorm/Restore will use the record filtering and relationship rules configured on the to find records within the selected Snapshot, only considering record versions modified from the start to the end of the provided date (/time).

If there are multiple versions of a record within the Snapshot, the version restored to Salesforce can be configured using the “Pick” dropdown. Available values include:

• Latest Version – restore the version with the most recent modification time.

• Earliest Version – restore the version with the oldest modification time.

If a record is in the Snapshot, but no version of the record has a modification time within the Point-In-Time Strategy interval, the record will not be restored.

This Point-In-Time Strategy will find records that were modified between:

• If a day is provided:

  • The beginning and end of the day.

  • For example, if “2021-05-10” is provided, CopyStorm/Restore will find record versions with modification date / times between “2021-05-10T00:00:00.000Z” and “2021-05-10T23:59:59.999Z”.

• If a day and hour is provided:

When the “Between Two Times” Point-In-Time Strategy is used, CopyStorm/Restore will use the record filtering and relationship rules configured on the to find records within the selected Snapshot, only considering record versions modified from the start to the end of the provided interval.

If there are multiple versions of a record within the Snapshot, the version restored to Salesforce can be configured using the “Pick” dropdown. Available values include:

• Latest Version – restore the version with the most recent modification time.

• Earliest Version – restore the version with the oldest modification time.

If a record is in the Snapshot, but no version of the record has a modification time within the Point-In-Time Strategy interval, the record will not be restored.

Though CopyStorm/Restore can faithfully restore Salesforce audit fields, there are a number of cases where the LastModifiedBy and LastModifiedDate fields cannot be restored. This article explains why.

If both the CreatedBy/CreatedDate and the LastModifiedBy/LastModifiedDate fields are not being restored accurately then the answer is simple. The Salesforce credentials in use are missing the necessary privileges to write to audit fields. See the article on Restoring Audit fields for instructions to enable this Salesforce feature.

If your Salesforce credentials do have the proper permissions, then several other conditions can cause the LastModifiedBy and LastModifiedDate fields to fail to match the values in the CopyStorm database. To understand the condition details, you must first understand what the option Salesforce permits on audit fields means. The permission that allows writing to Salesforce audit fields is called:

• Set Audit Fields upon Record Creation

The permission means exactly what it says: Audit fields can be set on a record INSERT but NOT on a record UPDATE. This “feature” is at the core of why CopyStorm/Restore cannot always restore the LastModifiedBy/LastModifiedDate fields to match what is in the backup.

The rest of this article describes scenarios where CopyStorm/Restore is forced to UPDATE records and thus change their LastModifiedBy and LastModifiedDate fields.

Though CopyStorm/Restore will always restore records in the optimal dependency order, circular relationships can make the order ambiguous. Consider the following case we have seen with multiple Salesforce instances.

• The Account table has a field called PrimaryContactId — a reference to a Contact record.

• The Contact table has a field called AccountId — a reference to an Account record.

Here is how CopyStorm restores these records.

1. Restore Account records and keep track of all occurrences of PrimaryContactId that are not yet known (because the Contact table has not yet been processed).

2. Restore Contact records.

3. Use the Ids on the restored Contact records to patch the Account.PrimaryContactId fields that were skipped when Accounts were inserted.

It is Step #3 that causes the LastModifiedBy/LastModifiedDate values on Account records to change to the Salesforce credentials running CopyStorm/Restore. Unfortunately there is no other choice since:

• Salesforce does not permit writing to audit fields on update.

• The Account records have to be created before the associated Contact records making step #3 required.

Some Salesforce record types are created as a side effect of creating another record and CopyStorm has no control of over the audit field values for records created by side-effect. Common examples include:

• ContentDocument records are created as a side effect of inserting a ContentVersion record.

• OpportunitySplit records can be created as a side effect of inserting an OpportunityTeamMember.

• ContentFolder records can be created as a side effect of inserting a ContentWorkspace.

There are a number of record types in Salesforce that do not support an INSERT operation when they are in specific state. In this case CopyStorm/Restore will often:

1. Create the record in a state that allows INSERT.

2. Update the record to match the original values in the database record to restore.

Step #2 causes the LastModifiedBy/LastModifiedDate values to be different that those on the original record in the backup. Common examples include Lead and Contract.

It is possible for the side effect of a trigger or workflow to cause an update on a record restored by CopyStorm/Restore. Though CopyStorm/Restore supports disabling of triggers/workflows during a restore, the problem still comes up for several reasons.

1. The CopyStorm/Restore user “forgets” to disable a trigger/workflow.

2. The trigger/workflow is part of a managed package and Salesforce does not support their disablement.

Users can expect 100% accuracy as much as they want but any application using the current Salesforce API will not be able to deliver this level of performance. The only choice we know of for getting 100% accuracy is to hire Salesforce to perform the restore and then pay many $$$ and wait. Once a 100% person sees the cost and wait time we suspect they will live with a few audit fields being different.

Release Date: 22.Aug.2024

This is a bug fix version upgrade release. As always, existing CopyStorm/Restore configuration files are backwards compatible.

Patch Levels

Release Highlights

This release focuses on customer experience and bug fixes. Notable items include:

• Salesforce Improvements & Bug Fixes: Restore of Salesforce knowledge articles when all articles are in an “archived” state. Prior releases require a version of the article to be active.

• Application Experience & Interface: Improve performance of restore candidate scanning when using Snapshots.

• EmailMessage.ActivityId: Fix Update Issue

  • Addresses an issue where CopyStorm/Restore attempts to update the EmailMessage.ActivityId field. The restore process now permits only INSERTS for this field.

• Knowledge Restoration: Improvement

  • CopyStorm/Restore now supports restoration of Knowledge Articles that are all in an “Archived” state

• Restore Set Editor: Fix for Record Selector Synchronization Issue

  • Fix an issue where the text area (for ID list, SOQL, etc.) resets unexpectedly

  • Fix an issue where ID File input does not persist properly

• Email Deliverability Notification: Improvement

Record Filters in CopyStorm/Restore provide an easy way to limit record selection without writing SQL. Following these steps will enable CopyStorm/Restore to restore a specific set of records to Salesforce.

To limit restored records to specific criteria:

1. Select the “Filter” in the “Which Records” dropdown.

2. Click on the empty filter to edit.

3. Create the criteria by dragging and dropping fields and references.

4. Test the filter and validate the criteria.

5. Press “Save” to apply the filter.

To enable filter-based record selection for a table:

1. Select the table in the Restore Set Editor.

2. Update the “Which Records” selector to “Filter”.

3. Click on the “Click Here To Edit” button to open the filter editor.

Edit the filter by dragging and dropping fields and operators from the left-hand side of the dialog into the right-hand tree.

Referenced data can be filtered by expanding reference fields in the field tree.

Click on an item in the right-hand filter tree to edit the criteria. Pressing “Save” will save changes in the criteria editor, and pressing “X” will delete the criteria from the filter.

To test the filter and verify that it is finding the correct records, press the Preview button. This will query the CopyStorm database for a sample set of records that match the criteria and display them in the table.

To view all fields in the query results, select “All Fields” in the “Show” drop-down. To view the SQL query that was generated, press the “Show Query” button.

If the query results are correct, press “Save” to save changes to the filter and close the dialog. To close the dialog without saving changes, press the “Cancel” button.

Parameters for controlling CopyStorm/Restore job logging and informational output.

Capstorm is commonly asked “How can I do a complete restore of my Salesforce?”, and the short answer is you cannot. This article explains why and the kinds of restores that occur in practice.

For a person coming from a traditional database world, how to do a complete restore is a simple question. Traditional databases allow an operator to easily disable database access and replace the image with a backup — this technique allows an operator to put a database into a known state at any desired point in time.

Salesforce, however, is unlike a traditional database in several important ways, making a traditional database restore impossible:

• It is impossible to get an exact point in time backup of Salesforce using the Salesforce API.

• Salesforce cannot be shutdown during the restore process. This often means that data entered by employees may be overwritten during while the restore is in progress.

This article describes the default behavior for restoring Knowledge articles and article versions when the One Version Per Push setting is turned off. The process works in batches, grouped by version number (e.g., CopyStorm/Restore restores all Version 1s, then all Version 2s, and so on).

Before restoring anything, CapStorm looks at all the article versions selected for recovery and sorts them into a very specific order. This “smart selection” prevents errors. The order of importance is:

1. Archived Articles First: It deals with the oldest, completed versions first to get them out of the way.

2. Online Articles Next: These are the active, published versions.

The Restore tab is used to launch a restore operation and view progress. This tab allows several operations:

• Estimate the size of a restore.

• Run a restore for the first time.

• Resume a restore from the point at which it last stopped.

The “Fields to Restore” editor determines which fields for each record will be restored to Salesforce.

• By default all fields are selected.

• If a field is not selected it will:

  • Be set to null for records inserted into Salesforce.

The Advanced Tab supports control of what Salesforce triggers, validation rules, flows, workflows, and restricted picklists are temporarily disabled during a restore. Note than any item disabled by CopyStorm/Restore will automatically be re-enabled when a restore completes or is cancelled.

Why are these features necessary? Let’s look at a few examples:

• There is a Salesforce trigger that initiates notifications for Opportunities larger than $50,000. During a restore running this trigger would be a bad idea.

• Validation rules have changed over time and much historical data will not pass the current rules. Disable the rules during a restore.

Control of the following item types is supported:

• Configure the scope of automation management to include Rules and Workflows from Managed Packages.

• Configure the timing of automation re-enablement.

Disabling triggers during a restore is a common necessity. For example, if an Opportunity trigger sends an email on large opportunity creation you will want to avoid this when restoring to a sandbox. Another common problem is triggers which are not designed to handle large blocks of records and when they receive a large block they exceed the Apex statement limit per transaction.

When a trigger is added using the Edit Trigger Selection button, CopyStorm/Restore will disable the trigger at the beginning of the restore process and re-enable it after the restore completes or is cancelled. Note that on a sandbox the disablement/enablement of triggers is relatively fast, but on a production environment changing the enablement status of a trigger will cause unit tests to run.

Disabling validation rules during a restore is a common process because older data will often not pass the current validation rules.

In most cases, letting CopyStorm/Restore manage validation rule disablement/enablement is sufficient. When this option is enabled:

• CopyStorm/Restore disables active validation rules for a table just before data is written to the table.

• Once updates/inserts to a table are complete, CopyStorm/Restore re-enables the validation rules it disabled in the previous step.

If updates to one table cause updates in another table (for example: an OpportunityLineItem change can cause an update to the Opportunity table) then it may be necessary to explicitly choose validation rules to disable. If a rule is explicitly selected then the rule will be disabled at the beginning of the restore process and re-enabled when the restore process completes or is cancelled.

If automatic management is enabled and a validation rule appears in the explicit list then the automatic management system will ignore the rule.

Disabling ProcessBuilder/Flows during a restore is a common necessity to avoid processing. For example, if an Opportunity flow sends an email on large opportunity creation you will want to avoid this when restoring to a sandbox.

When a Flow is added using the Edit Flow Selection button, CopyStorm/Restore will disable the Flow at the beginning of the restore process and re-enable it after the restore completes or is cancelled.

When a Flow is selected, the current version of the Flow is displayed. When CopyStorm/Restore disables the flow as part of the restore process, it will query Salesforce for the current active version – and disable the active version (and re-enable the disabled version when the restore is finished).

Disabling workflow rules during a restore is a common process to avoid a process that normally happens when a user enters/modifies a record via the GUI.

In most cases, letting CopyStorm/Restore manage workflow rule disablement/enablement is sufficient. When this option is enabled:

• CopyStorm/Restore disables active workflow rules for a table just before data is written to the table.

• Once updates/inserts to a table are complete, CopyStorm/Restore re-enables the workflow rules it disabled in the previous step.

If automatic management is enabled and a workflow rule appears in the explicit list then the automatic management system will ignore the rule.

Disabling restricted picklists during a restore is a common process to avoid encountering errors with older records whose values do not meet the criteria of the current picklist definition.

In most cases, letting CopyStorm/Restore manage restricted picklist disablement/enablement is sufficient. When this option is enabled:

• CopyStorm/Restore disables active restricted picklists for a table just before data is written to the table.

• Once updates/inserts to a table are complete, CopyStorm/Restore re-enables the restricted picklists it disabled in the previous step.