Mule Migration Assistant

In early July of 2020, Mulesoft released it’s Mule Migration Assistant (MMA) which automates some aspects of migration from Mule 3.x to 4.x.  Promised well over a year ago, better late than never.  The documentation can be found at https://docs.mulesoft.com/mule-runtime/4.3/migration-intro

I took the time to try out the migration process on a very simple project and see what lessons might be learned.  This article can be viewed as a description of what I did and a review of the tools.

The MMA application can be downloaded in compiled form from https://github.com/mulesoft/mule-migration-assistant/releases

It’s available as a tarball and a zip.  After decompressing it, you are left with an executable JAR called mule-migration-assistant-runner-1.1.0.jar, plus a collection of support libraries.

I created a trivial Mule project using Studio 6 called “mma-hello” using the 3.9.2 runtime.  A simple project demonstrates basic operation of the migration tool without complicating the results.  The mma-hello application logs a hello message and sets the response to hello world. 

The code looks like this:

And the XML source:

That’s about as simple as it gets.

To run the assistant, CD into your installed MMA directory.  Then:

java -jar mule-migration-assistant-runner-*1.1.0.jar [parameters]

Where documented parameters consist of:

For me, this works out to:

java -jar  mule-migration-assistant-runner-1.1.0-SNAPSHOT.jar \

-projectBasePath C:/Users/markj/AnypointStudio/personal-workspace/mma-hello \

-destinationProjectBasePath C:/Users/markj/AnypointStudio/personal-workspace/mma-hello-v4 \

-muleVersion 4.3.0

Note that this command is not fully described on docs.mulesoft.com, nor is it in the README file on GitHub.  Rather, you need to drill down a bit into the /docs of the cloned sources, but you can also use the  -help parameter to provide more help information:

Typically, the documentation is out of date regarding the actual application.  Note the addition of several proxy parameters that allow projects to be migrated in a secured environment.

Running the command above, I get:

Executing migrator 1.1.0-SNAPSHOT…

================================================================

MIGRATION ASSISTANT RUN SUCCESSFULLY

================================================================

Total time: 1.567 s

Migration report: C:\Users\markj\AnypointStudio\personal-workspace\mma-hello-v4\report\summary.html

The report is formatted as HTML:

Warnings include:

To have a look at the results, I imported it into Studio 7.4.  The resulting code looks like this:

There are several references to inbound and outbound properties here.  I think these are standard warnings regarding such properties, though none are set or used in the mma-hello example.  Still, this clutters up the XML code.  

Also notice the use of the DW function, migration::HttpListener::httpListenerResponseHeaders(vars).  This looks like it’s pushing vars into headers, but the original code doesn’t do that.  Perhaps this reflects the default behavior of the  3.9.2 HTTP connector.  In order for that information to continue to be present in the migrated application, it needs to be pushed into headers.

Finally, the original code in my 3.9.2 code comes across without any problem.

While these additional warnings are useful the first few times the migration assistant is used, it just adds clutter to the code.  This would be annoying if you needed to migrate 100 APIs and needlessly increases file sizes.

There are some things that the MMA won’t handle.  For example, it’s not all that surprising that Java classes don’t migrate since custom Java classes used in a Mule project would have a lot of references to the older object model.  Mapping the old model to the new one would be quite difficult.  Also unsupported are:

• DataMapper (manual migration to DataWeave is recommended)
• Custom types defined in Studio
• The <expression-component> element
• Any unlisted connectors or modules.

I had problems when I tried to include a Mule domain, but didn’t take the time to figure it out.  Caveat emptor!  

Overall, the Mule Migration Assistant can do a lot of the heavy lifting involved in migration.  The documentation suggests that you “prepare the code” for migration, like converting MEL expressions into Dataweave, but that kinda misses the point of a migration tool.  If you used DataMapper in your old projects, you are going to have to migrate them by hand to Mule 4 – no getting around that.  MMA will migrate standard connectors, but not third party or custom ones.  The report generated is helpful in pinning down where the problems are.  Warnings are too verbose, in my opinion, and there should be an option to reduce/eliminate them.  Warning comments will seriously clutter up converted XML.

Bear in mind that this review covers a VERY simple example.  More complex applications will be more difficult to migrate.  The support provided by the MMA only covers the mechanical parts of the conversion, which is a small part of a large application or set of interlocking APIs.  This is where assistance from experts like those provided by ArganoMS3 can help to make your migration process smooth, timely, reliable, and within budget.  Send an email to contact@ms3-inc.com to contact our migration team.

---

About the Author: Mark Norton

Mark Norton is a Senior Contributing Engineer focused on providing business integration solutions using Mulesoft (Certified Developer), AWS (Certified Business Provider), and other technologies. As one of the first team leaders, he has helped MS 3 grow and guide the members of his team on their career path and client work. As a proposal manager, Mark has led and supported several significant proposal efforts at federal and state levels, in addition to commercial opportunities. Before joining MS 3 in 2015, Mark managed his independent consulting firm that developed integration solutions for the Higher Education sector.