Replacing Legacy. Part 4: Business Logic Burden
To better understand the topic, I suggest becoming familiar with the previous parts:
In the previous chapters, we focused on a gap we must cover for transitioning from a legacy to a new model definition. The business logic layer is the next challenge to address.
Legacy systems contain multiple layers of business logic developed throughout the years of operation. Each layer usually represents a business context of a particular period. We believe such layers are added cautiously, avoiding impact on the previous layers, even if that is not always true.
Another notorious characteristic of legacy systems is outdated or lack of documentation. As a result, knowledge about a specific business logic is encoded in source code and kept in the minds of employees who work with that logic. That “people” knowledge is temporary: it vanishes with time and when employees leave an organization or join another team.
Thus, we again reference archeology, which has many historic layers buried under the ground without written pieces of evidence and other eyewitnesses. Handling that burden is one of a business analyst’s most complex tasks. I summarized a few thoughts on the topic following my experience.
Definition of Business Logic
“Business logic” is the first term I heard when I joined IT. It is a self-explanatory term everyone understands universally. As usual, with universal terms, everyone has their understanding.
I was surprised when I realized that neither BABOK v3 nor the “Software Requirements” explicitly defines what business logic means. So I turned to Wikipedia:
In computer software, business logic or domain logic is the part of the program that encodes the real-world business rules that determine how data can be created, stored, and changed.
But later in the article, it provides a bit of a conflicting statement with the definition mentioned above:
Business logic should be distinguished from business rules. Business logic is the portion of an enterprise system which determines how data is transformed or calculated, and how it is routed to people or software (workflow). Business rules are formal expressions of business policy. Anything that is a process or procedure is business logic, and anything that is neither a process nor a procedure is a business rule.
Not to spend more time battling on the terminology, let’s agree that within this article, I understand both workflows and business rules implementation as the business logic.
Starting Conditions
Considering the new model definition and modern business context, it is impossible to move business logic from the Legacy to the new system as-is. So, there is a gap to address in transitioning from AS-IS to TO-BE. But to make that leap, we must have a precise understanding (and preferably well-documented) of the AS-IS state.
The overall complexity of the task depends on the current phase of the Legacy support in an organization:
1) Active development
A development team keeps supporting old and implementing new features in a Legacy system. That means there is at least enough documentation, test cases, and BA artifacts for the new pieces. Also, some SMEs (Subject Matter Experts) know some parts of the system well. They might have a partial picture, but that is a good starting point anyway.
There are a few caveats here:
- The Team might not be happy to help you because, technically, your work will eliminate their work. Especially, when they work on an outdated technology stack that is not very popular on the market.
- The quality of their artifacts and knowledge, in general, might be low, so you would need to invest a lot of effort anyway.
- You need to keep up with their changes, which may need to be aligned with the vision of the Replacement system.
2) Support mode
There is no new functionality, but an internal or outsourced team supports a Legacy system by fixing bugs and making minor improvements. Or it can be a vendor. They possess little knowledge about the system compared to an active development team. And they are also not happy about your presence.
3) Hibernation
A Legacy system is not operational, so neither development nor support is happening. So, there are low chances to find up-to-date documentation or SMEs.
I can barely imagine why some organizations might need to replace a system not in production. But let’s keep that option for a better count.
Thus, your activities to reinstate the AS-IS state depend on those conditions. Please consider that when you estimate BA activities and choose strategy wisely.
Top-to-bottom & bottom-to-top approach
Business logic can be re-discovered with top-to-bottom and bottom-to-top approach:
Top-to-bottom: interviewing stakeholders to understand how the system works and mainly why it works that way, not another.
And remember that:
- you need to identify them first;
- some stakeholders are missed and, possibly forever;
- existing stakeholders might forget or miss something.
That is why we also need Bottom-to-top: learning how the system works by testing it or reviewing the source code.
Use those methods interchangeably: prove the words of stakeholders with current behavior. Refrain from trusting them unquestioningly, even ones who are very senior, and claim they know how everything works. Reality shows that it is not always the case.
So my main advice sounds doom-ish: “Don’t trust stakeholders. Don’t trust documentation. Trust tests that you executed and proved they are correct.” It is good when there are test scenarios or even automation tests. But if that is not the case, I encourage you to create them.
Moving to TO-BE without complete AS-IS
Based on the current business logic, together with stakeholders, you need to elaborate new logic aligned with the new model definition. And here is a caveat: you start working on the new/improved business logic for a Replacement system before you get a complete picture of the current logic. Simply because you are not paid to document the as-is state, you are paid to replace it.
So, while documenting and understanding the current process, you will also work on the TO-BE state in parallel. In this case, you must be very cautious about the scope of the pieces you analyze. The legacy system has layers that can be interconnected in sometimes very bizarre ways.
So, when you think you have done the analysis, you might get to redo it once again when you move forward and discuss some further system modules.
While working with Legacy, you will also start treating debt differently, as, during analysis, you face years of aggregated tech or business debt. Ideally, you must not move that kind of debt from the Legacy to the new system. But there might be cases when a proper solution requires revising the TO-BE state once and again and proceeding with a weaker solution is easier. That is all about compromises.
You might feel that Agile is unsuitable for such projects due to its iterative nature with frequent delivery. But that is not actually true. However, you need to get the full picture as quickly as possible to be able to decompose the system and address those pieces with as little re-work as possible.
Describing business logic
There are different ways of describing business logic, from textual to visual. Business stakeholders like fancy diagrams but are not good at reading heavy and puzzling pieces. No one is good at it, actually.
So, you have to translate them to the audience and carefully drive their understanding. Just sending them links to Lucidchart or PDF files with diagrams and asking for approval is a questionable approach that won’t be effective in the long run. Be prepared to hold multiple workshop sessions. Very quickly, you realize you know the system better than most experts.
Throwing AS-IS and TO-BE diagrams to the Development team is not enough.
As a Business Analyst, you will have to decompose the pieces and clearly articulate the scope of changes with acceptance criteria.
So, you’ll likely have different BA artifacts for the business and the implementation. That is a big deal once you reach a heavy cognitive load by supporting many artifacts.
I suggest minimizing that gap: whether devs become more proficient in BPMN diagrams or business stakeholders in reading details acceptance criteria.
Determinate a Decision-maker
Our best intention is to avoid moving the mess to the new system. The Legacy usually aggregates the layers of business logic, and their context can be lost in time and be overridden with the following pieces. It is a frequent case that someone requests a business rule implementation, and then something changes, and it becomes non-valid. So customers stopped using it without notifying developers or, worse, never used it. But the code continues to exist without questioning its relevance.
Remember, Legacy is usually an on-premise solution where developers are rarely involved in operation. Not mentioning any kind of analytics.
The purpose is to cut obsolete parts and move the important ones to the Replacement system. And there should be a person, not a Business Analyst, but a senior business stakeholder. Who must also be accountable for decisions if a cut piece appears vital for some parties.
For larger systems, there can be a group of persons responsible for specific business areas. And this is where politics enters the room. Most likely, such a committee will always choose the safest option: to move existing stuff to the new system so as not to cause potential issues.
The best option is to have a brave business leader who knows exactly what is required and clearly defines what needs to be migrated and how. I have heard that such people exist but have never met one.
But please, my dear Business Analyst, don’t put that burden on your shoulders.
Take care,
Ilya
