12 Tips for a migration and modernization project

Sometimes migration/modernization projects are hard to execute because there are many technical challenges, like the structure of legacy code, customer environment, customer bureaucracy, network issues, and the most feared of all, production bugs. In this post I'm going to explain the 12-step migration / modernization procedure I follow as a consultant using a tip-based approach.

I have some experience with this kind of situation because I’ve already passed by different kinds of projects with several kinds of problems. Over time you start to recognize patterns and get used to solving the hard problems.

So, I thought: Wouldn't it be cool to create a procedure based on my experience, so that I can organize my daily work and give the transparency that the customers and managers want?

To test this out, I did this for one customer in my hometown. They were facing a Red Hat JBoss EAP migration/modernization project. The results of the project were outstanding. The customer said they were even more satisfied with the transparency. The project manager seemed really comfortable knowing all about the details through the project and pleased with reducing the risk of unexpected news.

Let's get started with the procedure. This list includes organization and technical tips that can help achieve positive results in a migration/modernization project. There isn’t a specific execution order to these steps, so don’t worry about that. The only concern you should have, from my point of view, is to have all this in mind: Some of these tips may not be suitable for your scenarios, and that’s OK. These are only guidelines, not hard and fast rules.

It is important to mention that most of these tips are not exclusive to JBoss EAP. These can be applied to any project. Regardless of if it’s an OpenShift project or Red Hat Data Grid, it doesn’t matter. The whole idea here is to organize and execute.

1. If you don’t know it, or have doubts, ask for help.

Sometimes we are not 100% sure about our decisions, or we go in circles with technical issues. Should I apply this pattern? Why can’t I deploy my application? Why am I facing this NullPointerException? This is awful, isn’t it?

For situations like this, the answer that I found is: Ask for help and do it early. Simple, right? Sometimes the simplest answer is neither obvious nor easy. The pressure is huge when you are dealing with deadlines. So, take a deep breath and ask for help, while there's plenty of time to solve the problem and move on to the rest of the work. There are a lot of colleagues who are waiting for the opportunity to help someone; I count myself as one of them. Do not put even more weight on your shoulders, thinking that you must have an obligation to know something. That’s the true open source way of thinking.

2. If you want to ask or report something, do it, but do it using your email.

Another simple tip that can save you a lot of time and stress. If you want to ask or report something, even for a coffee (just kidding!), do it, but do so using your email. This is really important because words are, usually, lost in the wind, so write down everything that you need to your customer or project manager. Using this method can save you from the well-known situation: When was this requested, or why is it not ready yet?

Need a new user? Your credentials don’t work? Which is the git branch elected for the migration/modernization? No problem, ask it for an email. In the future, you will think: Thank goodness it was in an email, and that my manager was copied in it. (Obviously, if the proper procedure is to file a ticket in Jira or something like that, do it instead - but make sure there's a written record in the right system or systems!)

3. Report everything, but do it daily, ok?

Reporting is the essence of a migration/modernization project. It does not matter the situation, whether you are working with OpenShift, JBoss EAP, or any other technology. The important lesson here is: report your activities daily. If you are already doing this but it takes longer than five minutes, then you are probably doing it wrong. The idea here is to make it simple and summed up. This gives the crystal-clear transparency idea mentioned at the beginning of this article because it foresees future problems and gives time to do righteous planning.

If you feel insecure about it, try the template that I use.

• Activity 1
• Activity 2
• Activity 3
  • Observations

4. Who can access this application?

If you are facing a migration/modernization that involves applications and these should be modified to fit in the new product, like what happens in JBoss EAP, so it’s a good idea to request, using your email (see Report everything, but do it daily, ok? tip above), the users x profiles matrix.

With this information in hand, you can validate the application’s access in each scenario before reporting it as ready.

It is important to mention that it’s not an obligation as the customer is responsible for that kind of information, but it can help you prevent the question of why it was not tested for user X.

5. What should we test?

This tip is related to JBoss EAP migration/modernization projects, but you can fit it in other scenarios. Sometimes when you start working with a new customer, and new information starts appearing mid-project, one question often shows up: Is there a test plan?

Usually, the answer to this question is “no.” This is one of several critical moments that you’ll face in your professional life when you must be absolutely clear. Working without a test plan is to work with a 99% chance of failure because it directly impacts the customer’s approval. How will the customer be able to approve the work that you did without testing? How will you know what they consider "success"?

If you are facing this problem right now, bring in the project manager and your manager as soon as possible. Register everything in an email, and take a firm stance that the project must be put on hold until a comprehensive test plan has been provided to help ensure that the project won't be derailed down the line, preventing a high likelihood of failure.

6. Keeping track of activities is a good idea

If the project is facing problems with deadlines, and you think that you won’t deliver on time or that some of your coworkers are struggling with something,  schedule frequent meetings to talk to your project manager and include the customer. These frequent meetings can be daily with 15 minutes timebox, similar to Scrum methods. With this method, the customer can stay informed about details, the team will be more aware of what’s going on and (maybe) foresee if the delivery will happen or not.

7. Keep the good notes and records, you'll need them later

It is very normal to do research online during work to find solutions of any kind. However sometimes you might need to apply one previously used solution to another part of your code, but have since lost the web page address. Of course, you can look for it in your browser history, but this is boring and takes time.

So, this is what I recommend. I create a file (markdown or text file, doesn’t matter) and record every single web page address that I used there. If I find  some really useful solutions to use in my codet while browsing the internet, I add a new entry in this file and register the address. When I am building the documentation later on, I can use this file as a reference to justify my actions; or if I forget something, I can always find it again.

8. Keep a history of the commands you run, you may need them again.

Keeping a history of the JBoss CLI commands that I use has been beneficial to me. Before I started recording commands, I used to forget what I did, and in the end, it was hard to build good documentation. Now, using this technique, it only takes a copy-and-paste operation. I prefer to use a markdown file with segregated sections.

9. How can I measure the amount of work or time if I don’t know the application?

One question that typically surfaces  when you are modernizing an application is: How much time do you take? It is very tough to measure this because we, as consultants, might not know the application, and have no idea about the number of functionalities. Therefore, the only guide that we have is the application menu bar since we don’t usually get any kind of test planning or documentation. Based on that observation, I’ve crafted an idea about monitoring the evolution of the work in a big-picture scenario.

This idea took the shape of a spreadsheet. Below is an image that shows the concept.

There are several elements to understand in the spreadsheet. So I’ve numbered them as follows:

1. Menu item: Name of the menu item

2. Functionality: In my case, one menu item pops into some functionalities in a  1:n relationship. So I register 1 functionality per line.

3. Status: Items can be marked “Doing” or “Done.” You can use conditional formatting  to automatically make “Doing” cells yellow and “Done” cells green.

4. Period: This column keeps the dates in which I worked in one or several functionalities.

5. Observations: Some observations, notes, or to dos. Can be really useful if this spreadsheet is shared.

6. Functionalities: Amount of functionalities.

7. Migrated/Modernized: Amount of migrated/modernized functionalities. Every time you mark a status (third column) cell as DONE, this counter is incremented.

8. %: The percentage of work. The final result.

With this spreadsheet, I was able to communicate to the project manager and my manager about how long it takes to finish. The best part was I was not interrupted anymore.

Vinícius Camões, the project manager on this project, helped me with this spreadsheet. I had the idea, but he is a master of spreadsheet techniques. There is a template of this spreadsheet attached at the end of the article.

10. Is there a correct way to manage a Java application’s dependencies?

I had this question and couldn’t find any answers that could satisfy my will. That is until Renato Felix, whom I worked with for a JBoss EAP migration project, presented the JBoss EAP Bill of Materials (BOM). It was my first time working with one and I had no idea how important and helpful a BOM could be. Every time that you need to work with Maven dependencies in a JBoss EAP project, I recommend using a BOM. If one is already there but is out of date, update it. If there isn’t one, add it. This will assure that you are using approved and tested dependencies, and consequently, your application will benefit from it.

If you are working on a project outside JBoss EAP universe but it’s still Maven, try to google for a suitable BOM, like the one used by the Spring community. If there isn’t one, try to use trustable dependencies with community support and well-defined roadmap.

<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss.bom</groupId>
<artifactId>eap-runtime-artifacts</artifactId>
<version>7.2.6.GA</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

11. Organize your dependencies in an inline manner

It’s very normal to organize your Maven dependencies using your IDE’s indentation. If you have one, two or ten dependencies it’s OK, no big deal. But, what if you have twenty or thirty dependencies? Using your IDE indentation may cause a large pom.xml file and may make it really difficult to analyze your dependency tree. So, my recommendation is:

Instead of this

<dependency>
<groupId>org.jboss.spec.javax.ejb</groupId>
<artifactId>jboss-ejb-api_3.2_spec</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.jboss.spec.javax.jms</groupId>
<artifactId>jboss-jms-api_2.0_spec</artifactId>
<scope>provided</scope>
</dependency>

 

Use this

<dependency><groupId>org.jboss.spec.javax.ejb</groupId><artifactId>jboss-ejb-api_3.2_spec</artifactId><scope>provided</scope></dependency>
<dependency><groupId>org.jboss.spec.javax.jms</groupId><artifactId>jboss-jms-api_2.0_spec</artifactId><scope>provided</scope></dependency>

 

Inline dependencies are easier to analyze because normally the groupId section gets vertically aligned, and you can see the big picture clearly. Remember, this tip is not a silver bullet, you have to feel comfortable with this approach and see the need for doing it. It is important to mention, too, that this approach isn’t only related to Maven, it could be applied to other dependencies managers like Gradle. But remember, you must feel comfortable.

 

Thanks to Renato Felix for this tip.

12. Let’s modernize our view layer, JSF + Richfaces are easy peasy

Remember, it’s not that simple. It is, indeed, important to modernize your view layer if you’re planning to go to JBoss EAP 7 or later and using some older versions of JSF and Richfaces, but you must have in mind you’re entering a dark room and don’t know what’s coming. When I say older version I mean JSF 1.2 and Richfaces 3.

For situations like this one, use the How can I measure the amount of work/time if I don’t know the application tip. Analyze the application menu bar and try to clarify the situation because this modernization can be technically tough to do. I did one modernization in which JSF was 1.2 and Richfaces was 3.3.2, and it was chaotic. Why?

• JSF has its own way to manage the view objects and life cycle.

• Ajax calls aren’t easy to do, you have to understand the Ajax + Richfaces life cycle. Richfaces has special events for these Ajax calls.

• Due to the big difference between versions, many tags needed to be replaced. Newer tags, new unexpected behaviors.

• Some tags were discontinued causing pages to break like <rich:space>

• JSF 2.3 does not understand JSP anymore, so you will have to rename them to XHTML.

• Working with modals? Prepare yourself for a lot of changes. The tag <rich:modalPanel> doesn’t exist anymore; it was replaced by <rich:popupPanel>.

• Excess of container element can cause problems in rendering behaviors.

• The integration between JQuery and Richfaces does not work properly.

 

The list is extensive, and I don’t want to spook you. However, be prepared for work. Here are a few pages that were helpful in my research about this topic.

• RichFaces Migration Guide

• RichFaces Showcase

• StackOverflow: "Is it possible to change the /resources folder name?"

• Spacer implementation for JSF 2 or RichFaces 4

The big idea around this topic is huge because it fits almost everything: If you are trying to modernize some piece of technology and the gap between versions is big, have some caution. It probably will not be as easy as a walk in the park.

Conclusion

The migration and modernization of an application is almost like an art. You have to trust your instincts and create an organized method of working because it’s easy to get lost. The “organized” part of the job is the most important part that we as consultants should pay attention to. Organization results in transparency, and transparency is the key to success.

What I wrote in this article represents a process crafted during several customer assignments. In each one, I noticed what I could improve and tried not to fail in the next. Sure, I can and will improve more, but this article represents my two cents.