Making sense of software migration setup

A migration is not a copy. It is a controlled transfer with a beginning, an end, and a moment where the answer to "where does this live" changes for everybody at once. Most of the work happens before that moment, and almost all of the pain comes from skipping it.

This page is about the preparation: the dry run, the numbers you reconcile against, the freeze, and the runbook that means the day itself is dull.

What to take away

Decide what done means

Write the acceptance criteria before anything moves. Numbers, not adjectives.

Item counts by type on both sides must match within a stated tolerance, with every exception explained. A named list records things deliberately not moving.

A person checks a random sample, not chosen by the person who ran the transfer, and a stated position covers failures: fixed, moved by hand, or written off with somebody's agreement.

Formal records transfers work this way for good reason, and the published transfer guidance is a useful model even at a smaller scale.

The transfer is not complete when the copy finishes. It is complete when the receiving side has been verified against an agreed description.

The dry run

Take a slice of the estate that includes your worst cases and move it into a real destination, not a demonstration one.

Include the largest item, the deepest folder structure, filenames with accents and punctuation, something shared with an outside person, an item several people edit, and something produced by an automation. Twenty to fifty items is enough if they are chosen for awkwardness rather than convenience.

Then reconcile by hand, not with the tool's report, which will say success. Open each item and check contents, who can see them, and what happened to versions and comments.

Write down what did not survive, then share that list before the real move, because telling people beforehand separates a known limitation from a complaint.

Build the reconciliation numbers early

You cannot verify a transfer against a total you produced afterwards. Capture the counts before anything changes.

Items by type. Storage volume. Number of accounts, including the ones that are not people. Number of shared items, split by internal and external. Number of items owned by accounts that are already disabled, which is a category that surprises people. Take these from the source system's own reporting and save them with a date.

Do it twice: once when planning, once immediately before the freeze. The difference between the two is your growth rate, which is the only honest input to how long the transfer will take.

The freeze

A freeze is a period where content stops changing in the source so that the final copy is complete. It works when it is short, announced at least twice, and actually enforced by making the source read only.

Two failure modes. A freeze that is requested rather than enforced, which produces items created during the window and lost in the move. And a freeze that is too long, which pushes people into personal accounts and email attachments, creating an estate outside both systems.

Pick a window that spans the quietest period you have. Say what people should do if they genuinely must work during it, and mean it, because the answer being nothing at all is how work goes somewhere you cannot see.

Rollback, honestly

For most migrations of this kind there is no rollback. Once accounts are cut over and people have started working in the new system, going back means losing whatever was created there.

What you can have is a fallback, worth defining precisely. The old system stays reachable and read only for a defined period.

A named person can pause the rollout rather than reverse it. The criteria for that decision are written in advance, so the decision is made against a threshold, not how the day feels.

Treat this as contingency planning, not an optimistic schedule.

The contingency planning guide offers a reasonable frame: identify what must keep working, decide the acceptable interruption, then design around that instead of the transfer.

The runbook

One document, written in advance, that somebody else could execute. It contains the sequence, the person responsible for each step, the check that confirms each step worked, and the phone numbers.

Rehearse the first hour. The most common migration day problem is not a technical failure but that two people did step three simultaneously in different ways, and the second most common is that the person holding an administrative credential was unreachable. Both are solved by a rehearsal and neither is solved by a plan nobody read aloud.

Configure the destination before the transfer, not after, because permissions, sharing defaults, and retention are easier to set on an empty system. That is the practical argument in the advice on using cloud services securely.

Content that lands in a badly configured destination must be corrected item by item. The same order applies to file sharing setup: set the top level structure and sharing defaults before the first folder exists.

After the move

Keep the source reachable, read only, for a defined period, and tell people the date it goes away. Watch for the things that only happen monthly, because those fail four weeks after everyone has declared success. And write down what actually happened while it is fresh, since the next migration is cheaper only if this one left a record.

Where this fits

The category overview covers what does and does not survive a move in general. Everything wired into the old system needs its own plan, which is the subject of the connection rebuild. And the two moves most organizations do first, mail and storage, have their own specifics worth reading before you generalize from either.

Common questions

How long should the old system stay available?

Long enough to cover one full monthly cycle plus a margin, so at least six weeks. Set the date at the start, announce it, and keep it. An indefinite archive is one nobody ever closes and one you keep paying for.

Can we migrate department by department?

Often yes, and it reduces risk considerably. The cost is a period where two systems are live, which is bearable if the boundary between them is a rule anyone can state in one sentence. If people work across the boundary daily, staged migration is worse than a single cutover.

Who should run the reconciliation?

Not the person who ran the transfer. Checking your own work against your own expectations is the weakest form of verification available, and the person who ran the transfer already knows which items were awkward.

What if the numbers do not match?

Investigate before proceeding, every time. A gap of a few items is usually a definitional difference, such as whether deleted items in the recovery window are counted. A gap of a few percent is a real problem, and it will not explain itself later.