Replacing a legacy system: step by step, not on one cut-over date

With a switch-over on a cut-over date, everything happens at once: the data is transferred, every interface points to the new system, every user works in new screens from Monday. Each of these steps can succeed on its own and still fail in combination, and the fault only shows once the first real order runs through.

A cut-over date is like moving a workshop over one weekend. If one machine jams on Monday, the whole hall stands still, because the old layout has already been taken down. On top of that, a switch-over is hard to reverse once the first records exist in the new system: whoever switches back has to bring that data back into the legacy system.

This does not mean a cut-over date is always wrong. It means that the risk of a cut-over date grows with the number of modules that have to work together on that day. A step-by-step replacement keeps exactly that number small.

Martin Fowler describes the approach under the name Strangler Fig, after a fig that grows up a host tree until it replaces it. New functions are built separately from the legacy system, both run side by side during the transition, and behaviour gradually moves from the old system to the new one. Fowler stresses that breaking the system down into pieces that can be replaced one at a time is the actual core of the approach.

Technically, this needs a place where it can be decided which system handles a request. That can be an interface in front of the system which the portal, warehouse and accounting already talk to, or a database view behind which the tables are moved. This router is transitional architecture: it costs effort although it disappears again at the end, and it is still the reason why each individual move stays small.

If there is no such place, because users and external systems write straight into the legacy database, the replacement starts by building one. This first step brings nothing new for the business, but it shows who actually uses the legacy system.

Not every module can move at any time. Invoices need orders, orders need customers, and dunning needs invoices. A hard dependency of this kind means: a module can only run in the new system once its prerequisite already runs there, or it moves in the same stage as that prerequisite.

This gives a simple rule. Peripheral modules that no other module relies on move first, in the example shipping and quotes. An early move at a place with little traffic shows whether router, data synchronisation and operations work before a module the revenue depends on is due.

Modules that need each other, or whose prerequisite has to wait a long time itself, are harder. They lead to coupled moves, in which two modules change over in the same stage. A coupled stage is a small cut-over date inside the step-by-step replacement, and it deserves the most thorough preparation.

The calculator applies these rules. It takes a list of business modules, assigns an adjustable share of hard dependencies and plans stages from them in which at most the set number of modules move. Switch between cut-over date and step by step, and watch in which stage the invoices module changes over and whether that stage is outlined with a dashed line as a risk.

With the example values of the default setting, ten modules, two modules per stage and three hard dependencies, the plan has five stages. Invoices only move in stage 4, coupled to orders, which in turn wait for customers. Calculated as a cut-over date, all ten modules change over in one stage, and all three dependencies become coupled moves. With only one module per stage the risk disappears completely, but the plan grows to ten stages.

The numbers are stages, not weeks. How long a stage takes depends on the module, the data and the parallel run. What the calculator reliably shows is the structure: which modules wait, where couplings arise and which lever resolves them.

While a module moves, old and new run in parallel for one stage. That only adds safety if both results are compared. The router sends the same request to both systems, the legacy system stays authoritative for now, and every difference ends up in a log that someone reads.

Before switching over, it should be written down when the parallel run ends: for example once no unexplained difference has occurred over an agreed period and every known special case has run through at least once. Without such a criterion, the parallel run stays in place out of caution, and the team maintains two systems for longer than planned.

Differences are not always faults in the new system. Often the comparison reveals a rule that was never documented in the legacy system, such as a rounding step or a discount that only applies to one customer group. Findings like these belong in the description of the new module before the old one is switched off.

The most delicate question in a step-by-step replacement concerns the data. As long as a module exists in both systems, every data object needs exactly one leading system: customer master data is changed either in the old or in the new system, never in both. The other system receives a copy, and the direction of that copy only changes when the module moves.

In practice, this means creating a mapping table for identifiers early, because the new system assigns its own numbers, and deciding how often and in which direction data is synchronised. Letting both ends write at the same time creates conflicts that are hard to resolve later.

In the example, the customer portal is supposed to hand over orders early, but the orders module can only move in stage 4. The stage plan alone does not answer this. An interim solution at the router can accept orders from the portal, check them and write them into the legacy system through the existing path until the new module is ready.

Such an interim solution is deliberately transitional code. It should be built so that it can later be placed in front of the new module or removed, and it belongs in the plan with a date for its review. Otherwise the interim solution turns into another legacy system.

A step-by-step replacement costs a router, a parallel run and data synchronisation. These costs are not worth it in every case. A small system with few users and no integrations can often be switched over more cleanly on one well-prepared day.

1. The system is small: if all modules can be tested in one day, breaking it down brings little.
2. There is no place for a router: an application whose data can only be reached through its own user interface is hard to redirect section by section.
3. The data model cannot be split: if almost every table is written by almost every module, every stage becomes a coupled move.
4. The parallel run costs more than the risk: if a one-day outage is bearable, the preparation can be leaner.

Even then, part of the method remains useful. The list of modules and their dependencies shows what has to work together on the cut-over date, and therefore what should be tested together beforehand.

The first steps follow the same logic as the stage plan, and they can be started in-house. First comes a list of business modules with their users, data flows and hard dependencies, counted rather than estimated. Then every connection to other systems is described like a contract: format, direction, behaviour on failure and responsibility.

With this list, a peripheral module can be chosen as the first candidate, and it shows whether router, comparison and operations hold. Which documents a new module needs before another team runs it is covered in the guide Vom Proof of Concept in den Regelbetrieb (German). What needs to be settled for running an application in-house is described in Eine Anwendung im eigenen Haus betreiben, and how to spot shortcuts in the code that make every further move more expensive in Technische Schulden erkennen.

If a service provider is to accompany the replacement, the guide Prototyp weiterentwickeln lassen helps with the selection. An overview of software development at iiterate is on the page Softwareentwicklung.