In enterprise environments, data migrations look simple on paper. Then you are deep in large volumes of business critical documents, each linked to records that power daily work.
Aavenir's engineering team recently faced exactly that: moving more than 33,000 contract documents from a sandbox instance to production on ServiceNow. The files ranged from about 1 MB to 200 MB, each linked to detailed metadata and parent records in contract workflows. The goal was complete data fidelity, with no broken links and no lost files, in a process that could be repeated. Here is how the team did it, and what it teaches about migration in contract management.
The challenge: moving more than files
In a contract system, every document is connected. On ServiceNow, contract attachments are stored in the attachment table and linked to parent records, such as document revisions, which in turn link to contracts, parties and workflows. Moving a file without its link creates an orphan: the document exists, but nobody can find it from the contract.
So the team was not just transferring files. It was moving relationships, dependencies and business continuity. Three requirements were fixed from the start:
- Keep accurate parent and child record links for every document
- Handle very large files without bottlenecks
- Make the process repeatable and safe at enterprise scale
Approach 1: XML export and import
The team began with ServiceNow's native XML export and import. It is simple and works well for small datasets. At this scale, it quickly became unmanageable: data had to be split into batches of a few hundred to a thousand records, which slowed everything down and needed constant manual oversight.
- Pros: simple to configure
- Cons: manual effort, no scalability, little automation
The lesson was clear early on: manual processes do not scale for contract data.
Approach 2: API based migration
Next, the team automated the transfer using ServiceNow's REST APIs. That removed manual exports and gave more control. But the API transfers ran one attachment at a time, which created a new bottleneck.
- Pros: automated, consistent and reliable
- Cons: sequential, too slow for tens of thousands of documents
Approach 3: multi threaded migration with saved mappings
To scale, the engineers built a custom, multi threaded process in Python that combined ServiceNow's structure with parallel transfers.
- Temporarily detached attachments from their parent records by clearing the record link
- Stored the mapping in a temporary field so each attachment could be relinked later
- Migrated the parent document revision records to production
- Relinked attachments using the saved mappings
- Transferred the attachments through REST APIs using six parallel threads
The pipeline preserved every relationship and could be run again with the same result.
- Pros: fully automated, parallel, scalable
- Cons: needed scripting skills and live monitoring
The results
| Measure | Outcome |
|---|---|
| Documents migrated | More than 33,000 |
| Migration time | From about two days to about four and a half hours |
| Data loss or corruption | None found in validation |
| Process | Fully automated and repeatable |
Why it matters for contract management
Contract data is only valuable if it can be trusted. Transitions such as platform upgrades, mergers and new deployments are when trust is most at risk, because that is when documents and records are most likely to be separated. This project showed that careful design, automation and validation make large migrations predictable.
Whether you are moving thousands of legacy agreements into a new contract lifecycle management platform or consolidating instances after an acquisition, the same principles apply. Read our guide to contract migration.
Lessons for any migration
- Manual does not scale: XML exports and spreadsheets cannot keep up with enterprise volume
- Automation brings accuracy: APIs and scripts give consistent, traceable results
- Relationships are the hard part: map every link before moving anything
- Parallelize carefully: more threads mean more speed, but also more need for monitoring
- Validate everything: check counts, links and file integrity before switching over
- Contracts are data: treat them as connected records, not documents in a folder
How this shapes Aavenir's work with customers
The same discipline goes into customer migrations. When customers move contracts into Contractflow, the plan starts with the data model and the record relationships, not the files. Aavenir AI then extracts metadata from legacy contracts, and a person reviews the results before they become the record. On ServiceNow, migrated contracts sit under the same roles and audit history as the rest of the instance.
Planning your own migration
Before any large migration, write down the record relationships you must preserve, the largest files you expect, the validation checks you will run and the rollback plan if something fails. Run the process on a representative sample first, compare counts and links and fix what breaks. Only then run the full migration, with someone monitoring it live. That preparation is what turns a risky one off move into a routine, repeatable one.
The bottom line
Migrating more than 33,000 contract documents without losing a link took three attempts and one well designed pipeline. The takeaway for any contract team is simple: plan the relationships, automate the transfer, run it in parallel and validate everything.