How to Migrate Off a Salesforce Document Generation Tool Without Breaking It

Replacing a document generation tool in Salesforce is not a software swap. It is a migration of business logic that has accumulated, undocumented, in template files and query records for several years, plus a change-management project affecting everyone who has ever clicked a button to produce a quote.

Teams underestimate it for a consistent reason: generating one document with the new tool is easy, and it happens in the first demo. That success is misleading. The hard part is the eightieth document, the one that runs every January, the one whose logic lives in a Word field nobody has opened since 2021.

This is the vendor-neutral playbook: the phases, in the order that works, and what each one produces. If you already know which tool you are leaving, there are vendor-specific companions at the end covering the artifacts, gotchas, and cleanup particular to each one.

The core premise throughout: you cannot rip out a mature docgen install overnight, and you should stop trying to. A migration that works is incremental, runs alongside the old system for a while, and treats cleanup as a distinct phase rather than an afterthought.

Why "just switch it off" fails

Whatever tool you are on, the same four things make a clean break impossible.

Launch points scattered across the org. Detail-page buttons, list view buttons, flows, Apex, scheduled jobs, background merges triggered by automation. Each one is a separate place a document can be born, and most orgs have lost track of at least a few.
Logic that lives outside your metadata. Query records hold SOQL that encodes real business rules. Template files hold conditional logic inside Word, HTML, or XML. Neither shows up in a metadata dependency search, so "what does this document actually do" is often answered only by someone who may no longer work there.
Documents with a seasonal heartbeat. Renewal notices, year-end statements, annual compliance packets, quarter-end reporting. A document that runs four times a year will not surface its problems in a two-week test window.
Habit. People generate documents under time pressure. A button that moved, without warning, is experienced as an outage.

The failure mode is not "the new tool cannot render it." The failure mode is a document nobody remembered until the day it was needed.

Phase 0: Inventory before you evaluate anything

Do this first, before demos, before pricing conversations. You cannot evaluate a replacement against documents you have not enumerated, and the inventory is the artifact the entire rest of the migration runs on.

Build two registers.

The document register

One row per document family, not per template variant.

Column	Why it matters
Document name and business purpose	Distinguishes the ten that matter from the forty that exist
Primary object and related objects	Determines migration complexity more than page count does
Launch points (button, flow, Apex, batch, background)	This is your cutover checklist later
Who generates it, and how often	Identifies your pilot candidates
Frequency pattern (daily / monthly / quarterly / annual)	Flags the seasonal documents that need full-cycle validation
Business criticality and audience (internal, customer, regulator)	Sets blast radius and rollback urgency
Known pain (manual edits after generation, variants, breakage)	Ranks the migration order
Template variant count	The clearest single proxy for maintenance cost

Two shortcuts for building it fast: pull the list of buttons and quick actions referencing the vendor's namespace, and ask each team to name every document they produce from Salesforce. The gap between those two lists is itself informative, and it is usually where the forgotten annual document is hiding.

The docgen debt register

This is the list of things in your org that exist only because of the current document tool, the docgen debt you have been paying interest on. Build it during discovery, while you still have the templates and queries in front of you to prove the dependency. Do not delete anything yet. Phase 7 is where cleanup happens; recording it early is what makes that phase possible at all.

Typical entries, in roughly the order they appear:

Formatting fields. Formula or text fields that pre-format a currency, date, or address as a string because the template could not format it. Amount_Formatted__c, Close_Date_Text__c, and their relatives.
Flattening fields and rollups. Roll-up summaries, cross-object formula fields, and junction records that exist so a flat template could render a hierarchy it could not traverse.
Sort and sequence fields. Line-ordering fields written by automation purely so merge output came out in the right order.
Concatenation fields. A field joining several values into one string because the template could only place one merge field.
Vendor configuration records. Whatever your tool calls its packages, solutions, templates, and queries.
Integration plumbing. Remote site settings, named credentials, connected apps, integration users or dedicated licenses, permission sets granting access to vendor objects, custom settings holding configuration IDs.
Buttons and layout real estate. The buttons themselves, plus every page layout and Lightning page hosting one.
Reports and list views used as data sources, which look like reporting assets but are actually document infrastructure and will quietly break someone's dashboard if you delete them casually.

Two flags on every row: is it used anywhere else (a report, a validation rule, a flow, an integration), and who confirmed that. The fields that cause trouble at cleanup time are the ones that started as docgen-only and were quietly adopted by a report six months later.

Expect this register to be longer than you assumed. That length is the best evidence you will have when someone asks what the old tool actually cost.

Phase 1: Pick the alternative, and test it on your worst document

With the register in hand, evaluation gets much cheaper, because you know exactly which document to hand a vendor.

Do not evaluate on a clean invoice. Evaluate on the document at the top of your pain ranking: the one with nested data, the conditional clauses, the twelve variants, the manual correction step everyone accepted as normal. If a candidate handles that one, the rest is a formality. If it cannot, you learned that in week two rather than month five.

For the full evaluation checklist (pricing shape, what runs outside Salesforce, who owns maintenance, behavior on missing data), see our guide to evaluating a docgen replacement. Three criteria matter specifically for a migration, on top of the general ones:

Can it coexist? You will run both systems for months. If the replacement cannot sit alongside your current tool in the same org, on the same objects, you have lost the incremental path and are back to a big-bang cutover.
Where does the query logic go? Every merge query is business logic you are re-implementing. Ask concretely how the replacement gets related data, and whether the answer is "declaratively, in the template" or "write and maintain something new."
Can your admin own it end to end? If each migrated document needs a developer or a consultant, your migration rate is capped by their calendar, and waves two through six will not happen.

Phase 2: Freeze the old system

This is the highest-leverage decision in the plan, and it costs nothing.

From an agreed date, every new document is built in the new solution, and every change to an existing document triggers its migration. Need to add a clause to the renewal letter? That letter migrates now, and the clause is added there. No new packages in the old tool. No new template variants.

Without this rule, migration is a treadmill: you move six documents while the business adds four and modifies five. With it, the old library can only shrink, and effort concentrates naturally on the documents that are actually alive. Documents nobody has touched in two years migrate last, or turn out not to need migrating at all.

Publish one narrow exception: an emergency legal or compliance fix, where the change must ship in hours, may be made in the old system, with the migration ticket created at the same time. Name the person who can approve it. Track how often it is used, because a rising count means the freeze is not real.

Phase 3: Choose the first wave by pain, not by ease

The instinct is to start with the easiest document. Resist it. Migrating three trivial documents proves nothing, convinces nobody, and burns your credibility window on work that was never costing anyone anything.

Start with the most painful document that has a survivable blast radius. Rank by pain:

Minutes of manual correction after every generation
Template variants existing for what is conceptually one document
How often it breaks, and whether the fix needs a specialist
Support requests per quarter

Then temper with risk. The single highest-pain document might also be the one that goes to a regulator. If so, take the second-most-painful one first, learn on it, and come back. A good first wave is three to five documents from one team, high pain, internal or semi-internal audience, generated often enough to produce real feedback within weeks.

Frequency matters more than people expect. A document generated forty times a week gives you a signal in days. A quarterly document gives you a signal next quarter.

Run both, and compare output

For every document in a wave, generate it both ways from the same records, and diff the results. Not once: across a spread of real records, deliberately including the ugly ones. The record with a missing address. The one with sixty line items. The one with an empty optional section. The international one. The record everyone knows is weird.

This is the step teams skip, and it is where template assumptions surface. Keep the comparisons as a small library, because they become your regression test for every future template change.

Phase 4: Pilot with users who agreed to be pilots

Consent is not a formality here. It is what turns early problems into useful bug reports instead of complaints routed to your manager.

Ask, do not assign. Explain what is changing, what you need, for how long, and what happens if it goes badly. Let people decline.
Recruit from the pain, not from availability. The person who complains most about the current document is your best pilot. They have specific, well-formed opinions and they want the outcome.
Include at least one skeptic. A pilot group of enthusiasts will validate a document that does not survive contact with the rest of the team.
Timebox it. "Two weeks, then we decide together" is a commitment people accept. "We are moving you to the new system" is one they resist.
Do not pilot during period close. Quarter-end is the worst possible time to ask someone to try a new way of producing a document they need in ten minutes. Check the finance and sales calendars before picking dates.
Give them a direct line. A dedicated channel, a named person, and a response commitment. Pilot feedback routed through a general support queue arrives late and stripped of context.

Be explicit with pilots that the old path still works, and how to reach it. A pilot who feels trapped stops reporting problems and starts working around them, which is the exact behavior you are trying to eliminate.

Phase 5: Communicate more than feels necessary, and keep the escape hatch open

Communication cadence

The most common post-mortem finding in a docgen migration is not a rendering defect. It is "nobody told me the button moved."

A cadence that works, per wave:

When	Message	Channel
Two weeks before	What is changing, why, what stays the same, dates	Email plus team meeting
One week before	Short demo or two-minute recording, link to a one-page guide	Email plus chat
Day of	The new button is here, the old one is here, help is here	Chat plus an in-app note on the record page
Day 3	Reminder, common questions so far	Chat
Week 2	What we changed based on your feedback	Email plus chat
Before the hatch closes	The legacy path retires on this date	Email plus chat, twice

Three things matter more than frequency:

Put the message where the work happens. A note on the record page next to the button reaches people who never opened the email.
Lead with what did not change. "The document looks the same and goes to the same place; the button is now called X" is far more calming than a feature list.
Say what to do when it goes wrong, in the same message, every time. Not in a separate escalation document nobody bookmarked.

Educate on the delta, not on the product. Most users need to know where the button is and what to expect. Admins and power users need the deeper session. Do not put a rep through a template-building walkthrough.

The rollback path

Every wave ships with a documented way back.

Leave the old button in place, relabelled clearly (for example "Generate Quote (Legacy)"), moved to a less prominent position rather than removed.
Do not delete the old configuration records during migration. Deactivating a launch point is reversible in a minute. Recovering a deleted query record and its embedded logic is a different kind of afternoon.
Write the rollback trigger down in advance. What constitutes failure (wrong output on real records, a business-blocking defect unresolved past an agreed window, a compliance concern), who can call it, and how it gets communicated. Deciding this calmly beforehand beats deciding it at 4pm on a deadline.
Give the hatch its own sunset date. Kept open forever, it becomes a permanent parallel system and you never realize the savings. A reasonable rule: the legacy path for a document family retires after one full business cycle with no rollbacks and no unresolved feedback, announced twice before it closes.

The goal is an escape hatch that never gets used. An escape hatch nobody knows about is a failed migration; one that stays open indefinitely is an unfinished one.

Phase 6: Feedback, then the next wave

Close each wave with a real retrospective, not a status update. Ask pilot users four questions, in this order:

What did you have to fix by hand after generating?
What took longer than it used to?
What did you avoid doing because you were not sure how?
Would you go back? And if yes, to what specifically?

Question three surfaces silent failure. People do not report the feature they quietly stopped using.

Track a small set of numbers per wave, measured before and after:

Minutes of manual correction per document
Template variants for that document family
Document-related support tickets per month
Failed or re-run generations
Time from "I need this document" to "it is correct and sent"

Feed what you learn into the next wave, and say publicly what you changed because of the feedback. That is what makes the second round of pilot recruitment easy.

Phase 7: Decommission, in this order

Cleanup is a phase, not a cleanup task. Order matters, because each step is harder to reverse than the last.

Wait for a full business cycle. Every seasonal document must have run at least once in the new system. If you have annual documents, either wait for them or migrate and validate them explicitly against last year's output. This is the step that gets skipped, and the reason someone discovers in January that the year-end statement was never migrated.
Remove the launch points. Buttons off layouts, flow and Apex references retired, scheduled jobs disabled. Nothing can be generated by the old tool anymore. Fully reversible.
Deactivate rather than delete. Turn off configuration records and automation. Let it sit for a cycle.
Export and archive. Before deleting anything, export the templates, the query records with their SOQL, and the configurations to a repository. This is your institutional record of what those documents used to do, and someone will want it during an audit.
Now work the debt register. For each item, verify it is genuinely unused (dependency check, field usage, a search across reports, list views, flows, validation rules, and integrations), then deprecate before deleting: rename with a ZZ_ prefix, remove it from layouts, leave it a cycle. If nothing complains, delete it. Items that failed the "used elsewhere" check stay, and get documented as owned by their new purpose rather than by docgen.
Then the commercial step. Only after the org is genuinely clear should you cancel or downsize the license. Check your renewal date early: it should shape your wave schedule, but it should never compress validation of a seasonal document.

The debt register is where the migration actually pays off. Removing twenty fields, three junction objects, and a set of integration users that only ever existed to feed a merge is a permanent reduction in the surface area of your org, and it keeps returning value long after the last document moves.

Vendor-specific guides

The phases above are the same everywhere. What changes is the footprint: what the tool leaves behind in your org, where its logic hides, and which parts are hardest to unpick. Each guide below covers the artifacts, gotchas, and cleanup specific to one tool.

Migrating off Conga Composer: merge queries as undocumented business logic, URL button parameters, and solution sprawl.
Migrating off Nintex DocGen: DocGen Packages, the loop namespace footprint, and data sources bound to reports and Visualforce pages.
Migrating off S-Docs: a native-to-native move, where the driver is the authoring model rather than architecture.
Migrating off Docusign Gen: separating document generation from e-signature without disturbing your envelopes.
Migrating off Formstack Documents: when most of the configuration to migrate lives outside Salesforce entirely.
Migrating off PDF Butler: DocConfig sprawl and data-flow questions in a security review.

Where ZeroExport fits in this plan

ZeroExport is a native, structure-aware document generation engine that runs entirely inside Salesforce as a managed package. A few properties matter specifically for a phased migration:

It coexists. Installing it does not disturb an existing document tool. Both can run in the same org, on the same objects, so the wave-by-wave and side-by-side approach above is available rather than theoretical.
No middleware to stand up first. There is no external service to procure, authenticate, or clear through a security review before wave one, which removes the usual months of runway ahead of a migration. This was the highest-demand capability in our research corpus by a wide margin (362 distinct discussions).
Admin-owned templates. Templates are built in a native WYSIWYG builder inside Salesforce, so migration throughput is not capped by a developer's calendar.
Structure-aware rendering handles the nested and conditional cases that produced most of your template variants: deep nested hierarchy rendering, auto-detected repeater boundaries, section-level visibility that cascades, and adaptive layout when data is missing. That is what lets several variants collapse into one template with conditional sections.
A build-time warning system surfaces structural problems before you ship, which is useful during parallel-run validation on the ugly records.
Per-record override covers the "this one customer needs a different clause" case that otherwise spawns another template.

Being straight about the limits, because a migration plan built on a wrong assumption is worse than no plan: reusable blocks (define a structural section once and propagate it across many templates) are on the roadmap, not shipped, so today the model is one template per document family with conditional sections inside it. On raw rendering performance at very high volume and pixel-exact page-break control, we publish no claims: evaluate any candidate, including this one, against your own requirements in Phase 1.

FAQ

How long does a Salesforce document generation migration take?

It depends far more on document count and business cycle than on tooling. A useful planning shape: two to four weeks for inventory and evaluation, three to six weeks for the first wave including pilot and feedback, then subsequent waves at a faster cadence, plus one full business cycle before decommissioning. The freeze rule in Phase 2 affects the total timeline more than the speed of any individual migration.

Can two document generation tools run in the same Salesforce org?

Generally yes, and for a phased migration you need that to be true. Managed packages from different vendors coexist, and you control which buttons and automation point where. Confirm it explicitly for any tool you evaluate, because it is what makes incremental adoption possible.

Which documents should I migrate first?

The most painful ones with a survivable blast radius: highest manual correction, most template variants, most frequent breakage, generated often enough to produce feedback within weeks. Not the easiest ones. Easy documents prove nothing and consume the goodwill you need for the harder waves.

Should I cancel the old license as soon as the first documents move?

No. Cancel only after every document, including seasonal and annual ones, has run successfully in the new system for a full business cycle, and after the old launch points have been removed. Check the renewal date early so it can shape the wave schedule, but do not let it compress validation of a document that runs once a year.

What is a docgen debt register?

A list of everything in your org that exists only to serve the document tool: formatting and concatenation fields, flattening rollups and junction objects, sort fields, vendor configuration records, integration users, remote site settings, permission sets, and buttons. You build it during discovery and work it during decommissioning, deprecating each item before deleting it.

How do we avoid breaking a document that only runs once a year?

Identify seasonal documents in the Phase 0 register by frequency pattern, and either wait for their natural run before decommissioning or migrate them deliberately and validate against last year's output on the same records. Never let a license renewal date compress this step.