At a high level, when Universal Migrator restores data, it connects to APIs at the destination system and rebuilds records based on information in the backup.
Dependency-Aware Ordering
Universal Migrator inherently knows that some record types must be restored first because other objects depend on them. For example, Users, Practice Areas, and Contacts will often restore before Matters. If you simply tell Universal Migrator to restore everything, this dependency ordering will apply.
However, if you tell Universal Migrator to only restore matters, it will not make any attempt to restore contacts at all, even contacts that will be necessary for those matters to succeed.
Data Layering
When Universal Migrator restores a record, it does so by "layering" information into the destination system. For example, when processing contacts, Universal Migrator might do the following:
- First, create 'empty' contacts that just consist of names
- Then, layer on email addresses, phone numbers, and postal addresses.
- Then, layer on employer/employee hierarchies.
- Then, layer on custom field values.
While some systems may support bulk/aggregate APIs, Universal Migrator intentionally does not use those APIs because they tend to be fragile and actually increase the total time of the migration.
All bulk APIs are different, but in general, they tend to respond in similar ways which are not good for data migrations.
For example, lets say you want to restore a batch of 100 contacts and a single contact has a single custom field value that is invalid. Bulk APIs tend to respond in one of the following ways:
- "One of the contacts had an invalid value. So we didn't process any of them".
- "We processed 99 contacts successfully but one completely failed. Go figure out which one errored and why".
- "We processed everything you wanted but one field didn't go through right. Here's a warning message that requires a human to read and figure out what went wrong where."
By layering the data, if there is an issue, Universal Migrator gains deep insight into the cause and source and enables you to tweak and retry the restore for that record.
Automated Tweaks
When records are restoring, Universal Migrator may automatically make minor tweaks depending on requirements in the destination system. For example, if a destination does not allow matters with an empty description, Universal Migrator may provide a default value automatically. Universal Migrator will never change or ignore wrong data - its automated tweaks are limited to ones that are minor and do not affect the correctness of the record that is restored.
Successfully Restoring a Record
In order for a record to successfully restore into a destination system:
- All required dependencies:
- Must exist inside the migration database
- Must have a valid, non-blank Result_Id value
- All optional dependency values:
- Must be blank or exist inside the migration database
- Must have a valid, non-blank Result_Id value
- Any Destination-Specific requirements must be met.
Only dependencies that are used by the destination system are validated.
For example, if a matter is linked to an invalid matter stage but the destination system does not support matter stages, then
As an example, assume we have a matter with the following values:
| Column | Value | Implied Rules |
| Final_ClientContact_Id | ADEOUI | If the destination system supports contacts, the contact with Id 'ADEOUI' must have a valid Result_Id |
| Final_PracticeArea_Id |
| If the destination system supports practice areas, it must allow matters with no practice areas. |
| Final_MatterStage_Id | UEOA | If the destination system supports matter stages, the matter stage with Id 'UEOA' must have a valid Result_Id. |
| Final_ReferenceCode | ABC.001 | If the destination system supports matter numbers, it should try to create a matter with ABC.001 as the matter number. |
| Final_Subject |
| If the destination system supports matter names, it should try to use a blank name if possible and if blank names are not supported, it should use a default value instead. |
| Final_Description | 2019 Divorce with Children | If the destination system supports matter descriptions, it should try to use '2019 Divorce with Children'. |
Common Reasons Records Fail to Restore
Missing Records
Some legacy systems do not maintain referential integrity between records. This means that it is possible for Matter #15 to be linked to Contact #10, but Contact #10 might no longer exist. If you backed up one of these systems, you must do one of the following:
Have the client fix the issue in their legacy system and then re-backup
OR
Create a new Contact #10 in the migration database with the matching primary key value of 10.
OR
Update Matter #15 to reference a contact that does exist using a query similar to the following:
- --Update just Matter #15
- UPDATE __M_Matters SET Final_ClientContact_Id ='11' WHERE Id = '15'
- --or Update all matters linked to Client #10
- UPDATE __M_Matters SET Final_ClientContact_Id ='11' WHERE Final_ClientContact_Id = '10'
Not-Yet-Restored Records
Universal Migrator inherently knows that certain record types must be restored in certain orders. This means, for example, that staff members, practice areas, and contacts will be restored before matters because matters can have dependencies on these types of data.
In the event that there is an error restoring a "parent" record, any items that depend on that record will not be able to be restored until the issue is resolved. For example, if Matter #15 is linked to Contact #10 but an error occurred restoring Contact #10, then Matter #15 will error and indicate that it could not complete because it was missing the client.
Related Articles
01 - How Backups Work
When you look at all the different CRM, practice management, and document management systems, they all store and access data differently. Some are cloud based, others are on-premise. Some expose JSON APIs, while others use any number of database ...
03 - How We Expect Consultants to Work
The team at Universal Migrator supports over 200 data and document migrations every single month. These migrations are performed by consultants worldwide who are servicing law firms of different sizes with varying needs and requirements. The training ...
Training: Overview
Welcome to the Migration Academy! This series will help you learn everything you need to know in order to deliver high-value, rock-solid data and document migrations. Completion of the academy generally takes 4-8 hours and is required in order to ...
02 - Restore-Specific Database Columns
The following columns are commonly used when Universal Migrator is restoring data into a destination system. Restore Ordering and Priority Batch_Number The Batch_Number allows you to mass-segment data. Only the data with the lowest Batch_Number in ...
03 - Scoping your First Migration
When a patient needs an operation, a good surgeon gets as much information as possible from the patient before recommending a course of action or providing a quote. By taking this approach, the surgeon can provide a better, more informed experience ...