Legacy System Migration Do’s and Don’ts


Legacy sys­tems rep­re­sents a mas­sive, long-term busi­ness in­vest­ment, mak­ing a mi­gra­tion pro­ject an in­evitable con­se­quence of age­ing soft­ware sys­tems. Legacy sys­tem mi­gra­tion has many traps, but like all traps - if you know they are there - they can be avoided or even turned into an ad­van­tage. In this ar­ti­cle I will talk about some of the do’s and don’ts from my ex­pe­ri­ence work­ing on these types of pro­jects. At the end of the ar­ti­cle I will give some prac­ti­cal ad­vice and lay down a high-level strat­egy that has worked for me.

What is a legacy mi­gra­tion?

A legacy mi­gra­tion is the process of mod­ernising old, out­dated soft­ware with more mod­ern tech­nol­ogy. All tech­nol­ogy re­quires mod­ernising at some point. Think about it this way, you’re not still us­ing that Motorola Razor from 2007. Many legacy sys­tems run busi­ness crit­i­cal func­tions so it’s crit­i­cal to ex­e­cute a mi­gra­tion suc­cess­fully.

Conceptually soft­ware ap­pli­ca­tions can be split into two gen­eral parts - state and be­hav­iour. The state of an ap­pli­ca­tion is the data and what it means. The be­hav­iour of an ap­pli­ca­tion is the func­tion­al­ity and how it be­haves. This is in­grained into most soft­ware de­vel­op­ers and we learn this very early through tech­niques like ob­ject-ori­ented pro­gram­ming. An ob­ject is a way to en­cap­su­late state and spec­ify be­hav­iour.

The state of a soft­ware ap­pli­ca­tion is its data. The be­hav­iour of a soft­ware ap­pli­ca­tion is its func­tion­al­ity.

By split­ting the ap­pli­ca­tion into these two gen­eral parts we can be­gin to form a plan of how to mi­grate a legacy sys­tem to the cloud.

Data (State) Migration

There is great vari­a­tion be­tween the ways you end up with need­ing to un­dergo data mi­gra­tion. You may be do­ing a mod­erni­sa­tion soft­ware pro­ject so you only have to move from a legacy data­base to cloud com­put­ing. Or, you may be part of a merger and ac­qui­si­tion - and in this case - you of­ten end up with two or three sep­a­rate sys­tems that need to be com­bined. The chal­lenges are dif­fer­ent but the most im­por­tant thing is you will need to do a lot of analy­sis and map­ping.

Do not hand code the map­ping! You must find a tool - or set of tools - that will man­age the map­ping and do the data mi­gra­tion. I use an ap­proach to soft­ware called model-dri­ven en­gi­neer­ing (MDE) and one of the com­mon things we do is called model-to-model (M2M) trans­for­ma­tions. If you treat the legacy data­base schema as one model and also treat the cloud data­base as an­other model, then you can use M2M trans­for­ma­tions to get from one to the other. My favourite M2M tools comes from Codebots.

One last point I would like to make on the data mi­gra­tion is the qual­ity of the data you will en­counter. A word of warn­ing, it’s most likely go­ing to be hor­ri­ble. Over the years it would have been up­dated and ma­nip­u­lated by many de­vel­op­ers - for­eign keys will be miss­ing, it won’t be 3rd nor­mal form, columns will be in­cor­rectly named, or my favourite, the su­per col­umn where some­one dumps an ar­ray of data. All these prob­lems add up to a big prob­lem and are the rea­sons why data mi­gra­tion is so dif­fi­cult. This em­pha­sises the need for a sys­tem­atic map­ping tool of sorts.

Functionality (Behaviour) Migration

Data is the state of an ap­pli­ca­tion while func­tion­al­ity is the be­hav­iour. An ex­am­ple would be some­thing like a work­flow. It is a com­mon busi­ness prob­lem to raise some sort of work re­quest. Delegate that re­quest to a worker and then track the re­quest through to its com­ple­tion. If you can think of any sort of func­tion­al­ity of your favourite soft­ware - this is the be­hav­iour.

Now for the bad news. Believe it or not, data mi­gra­tion is the eas­ier of the two. Functionality mi­gra­tion is far more time con­sum­ing. The rea­son for this is sim­ple. Once you have iden­ti­fied what the func­tion­al­ity is - hope­fully doc­u­ment­ing it into some re­quire­ments or de­sign doc­u­ments - a soft­ware de­vel­oper then has to write the code for it. It’s like start­ing a green­field pro­ject.

Now for the good news. Recall I men­tioned ear­lier about an ap­proach to build­ing soft­ware called model-dri­ven en­gi­neer­ing. Another com­mon thing we do is called model-to-text (M2T) trans­for­ma­tions. These are ef­fec­tively like code gen­er­a­tors - or like ro­bots - and can do a lot of the heavy lift­ing when it comes to writ­ing the func­tion­al­ity. Using these tech­niques can save a lot of time, lift the qual­ity of the pro­ject, and re­duce the risk of the pro­ject fail­ing.

The Do’s and Don’ts
  1. Do more analy­sis
  2. Do test­ing, test­ing and more test­ing
  3. Do use a sci­en­tific ap­proach
  4. Do set both tech­nol­ogy and or­gan­i­sa­tion KPI’s
  5. Do use model-dri­ven en­gi­neer­ing
  6. Don’t do it all at once
  7. Don’t un­der­es­ti­mate the size of the prob­lem
  8. Don’t leave the data mi­gra­tion as an af­ter­thought
  9. Don’t think it’s go­ing to be easy
  10. Don’t stress!

How to do a legacy mi­gra­tion

Step 1: Ensure you have a sys­tem­atic path of data at the end

This is done through an au­to­mated step that re­verse en­gi­neers the en­tity model from the legacy data­base. When you get to the mi­gra­tion step it’s im­por­tant to main­tain a path for the data. This is known as a lift and shift. Some of the more im­pact­ful ben­e­fits of the legacy mi­gra­tion and the mod­ern tech­nol­ogy stack may only be re­alised once the data is mi­grated.

Step 2: Create your re­quire­ments back­log

As with any soft­ware pro­ject, there must be a re­quire­ments back­log. This keeps a team aligned and fo­cused on the up­com­ing de­liv­er­ables. It’s crit­i­cal for the prod­uct owner to live and breathe the re­quire­ments back­log.

Step 3: Determine what can be au­to­mated by tech­nol­ogy

I’ll elab­o­rate fur­ther on this be­low. Essentially we want to iden­tify re­peat­able pat­terns that ex­ist across the legacy sys­tem. In do­ing so, we can model these pat­terns and ef­fec­tively lever­age tech­nol­ogy. Our tech­nol­ogy of choice is Codebots which al­lows us to stream­line de­vel­op­ment when it comes to step 5.

Step 4: Don’t for­get to de­sign for mo­bile

User ex­pe­ri­ence is crit­i­cal. While we can try to an­tic­i­pate the man­ner in which users will en­gage with an ap­pli­ca­tion, given a big enough sam­ple size there will al­ways be out­liers. Rather than ig­nor­ing the mi­nor­ity, it does­n’t take long to set some break points and cre­ate a friendly mo­bile ex­pe­ri­ence.

Step 5: Utilise tech­nol­ogy plat­forms

This is per­haps the biggest area of op­por­tu­nity and some­thing that can dif­fer­en­ti­ate soft­ware de­vel­op­ment com­pa­nies. We utilise the Codebots plat­form which takes the data mod­els in step 1 and the re­peat­able pat­terns in step 3 to help write a sig­nif­i­cant por­tion of the code­base. Of course, it will never get us 100% of the way there as every sys­tem has cus­tom busi­ness logic but it can help save a lot of time, es­pe­cially when it comes to legacy mi­gra­tions.

Step 6: Migration

This is where you mi­grate the data as well as your users onto the new, mod­ern sys­tem. I’d rec­om­mend en­sur­ing there is a clear mi­gra­tion path. That starts with step 1. It’s im­por­tant to repli­cate the same un­der­ly­ing data model be­fore mak­ing any new changes.

There is no sil­ver bul­let or magic wand that can be waived to solve this prob­lem. You have to roll up your sleeves and work hard to achieve the de­sired re­sult. The six-step process I’ve out­line above and in the graphic be­low is one that works for us.


Legacy mi­gra­tion can seem like a scary process to a lot of busi­nesses, but it’s of­ten a nec­es­sary one. Using a tried and tested method such as our 6-step ap­proach can po­ten­tially not only al­le­vi­ate some of the traps but even help you trans­form the legacy mi­gra­tion process into a ben­e­fit for your com­pany.


Discover Software


Eban Escott

Big pic­ture thinker and Star Wars fa­natic

Get cu­rated con­tent on soft­ware de­vel­op­ment, straight to your in­box.

Using the fire­cracker method for legacy mi­gra­tion

02 March 2020

Mitigating the risks of brown­fields de­vel­op­ment

21 April 2020

Web Apps vs Excel: Which to Use When

20 October 2020

Your vi­sion,

our ex­per­tise

Book a con­sul­ta­tion