--- title: How Aavenir Migrated 33,000 Contract Documents | Aavenir url: https://aavenir.com/how-aavenir-migrated-33000-contract-documents/ description: How Aavenir engineers moved more than 33,000 contract documents between ServiceNow instances with every record link intact, and the lessons for migration. updated: 2026-11-07 --- [Home](https://aavenir.com/) / [Blog](https://aavenir.com/blogs/) / Migrating 33,000 contract documents Engineering # How Aavenir migrated more than 33,000 contract documents without losing any data Moving contract files is easy. Moving them with every relationship intact, at scale, is an engineering problem. SB **Shishir Bose**Nov 20, 2025 ยท 4 min read 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. Key takeaways - Contract documents are connected records, not just files, so relationships must move with them - Native XML export and import worked but did not scale - Sequential API transfers were automated but too slow for the volume - A multi threaded approach with saved record mappings moved everything with links intact - The result was a repeatable process, cutting migration time from about two days to a few hours ## 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 **Facing a large contract migration?**Tell us where your contracts live today. We will walk through how to move them with their data and links intact. Schedule a demo ## 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](https://aavenir.com/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](https://aavenir.com/solutions/enterprise-contract-management-software/), 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. ### In this article - The challenge: moving more than files - Approach 1: XML export and import - Approach 2: API based migration - Approach 3: multi threaded migration with saved mappings - The results - Why it matters for contract management - Lessons for any migration - How this shapes Aavenir's work with customers - Planning your own migration **Plan your contract migration with us**Bring a description of your legacy contracts. We will walk through how we would move them with their data and links intact. Share [in](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Faavenir.com%2Fhow-aavenir-migrated-33000-contract-documents%2F)[X](https://twitter.com/intent/tweet?url=https%3A%2F%2Faavenir.com%2Fhow-aavenir-migrated-33000-contract-documents%2F&text=How%20Aavenir%20migrated%20more%20than%2033%2C000%20contract%20documents%20without%20losing%20any%20data) Frequently asked questions (FAQ) ## Frequently asked questions ### ### How did Aavenir migrate more than 33,000 contract documents? The team detached attachments from their parent records, saved the mappings, migrated the parent records, relinked the attachments and transferred files through REST APIs using six parallel threads. Validation found no data loss. Read the [contract migration guide](https://aavenir.com/contract-migration/). ### ### Why is contract migration harder than moving files? Contract documents are linked to records such as revisions, contracts, parties and workflows. Moving a file without its links leaves an orphaned document nobody can find from the contract, so relationships must be mapped and preserved. Explore [Contractflow](https://aavenir.com/solutions/enterprise-contract-management-software/). ### ### Can Aavenir help migrate legacy contracts? Yes. Migrations start with the data model and record relationships, then Aavenir AI extracts metadata from legacy contracts and a person reviews the results before they become the record, on ServiceNow or standalone. See [AI contract extraction](https://aavenir.com/platform/ai-contract-extraction/). Have a question we have not answered? [Ask the Expert](https://aavenir.com/contact/) ## Keep reading [Contract repository Contract migration: why, when and how to move your contracts A practical guide to contract migration: why to centralize contracts, when to start, a six step process and the practices that keep migrated data accurate. Read more](https://aavenir.com/contract-migration/)[Contract lifecycle management Enterprise contract management: a complete guide What enterprise contract management is, the contract types and challenges large organizations face, the benefits of software and the features to insist on. Read more](https://aavenir.com/enterprise-contract-management/)[ServiceNow procurement ServiceNow Sourcing and Procurement Operations, connected to contract management How connecting contract lifecycle management to ServiceNow Sourcing and Procurement Operations reduces rogue buying, version errors and risk across procurement. Read more](https://aavenir.com/elevate-servicenow-sourcing-and-procurement-operations-spo-with-connected-contract-management-solution/) Schedule a demo ## See your contracts run on one record. - **1****A 30 minute walkthrough**Built around your team, whether that is procurement, legal, IT or finance. - **2****Your contracts, not ours**Bring a few sample agreements and watch Aavenir AI extract and review them. - **3****ServiceNow or standalone**We show the deployment that fits the systems you already run. Prefer to talk first? [Contact the team](https://aavenir.com/contact/). The form did not load. [Contact the team](https://aavenir.com/contact/) instead, or refresh the page.