Schedule a Call

Mule 3 Upgrade | Mule 3 to Mule 4 Migration Tool

With our focus on API-led integration, we take a look at the strategies, approaches, and tools available for a Mule 3 to Mule 4 upgrade on MuleSoft Anypoint Platform, to bridge the gap between the Mule 3 and Mule 4 runtimes, including the Mule 3 to Mule 4 migration tool, the Mule Migration Assistant. 

MuleSoft Version and Support

People have been building integrations with MuleSoft for a number of years, simplifying the movement of data between systems and providing customers with a connected digital experience.  As the MuleSoft platform grows and evolves new versions are regularly released, and since 2013 at least one new version has been made available each year. Given the releases change fairly regularly it is important to understand the different upgrade approaches that are available.

In March of 2018, MuleSoft released Mule 4, version 4 of the Mule Runtime (version 4.1), bringing with it many new features and capabilities. This included an overhaul of the Mule application structure, connectors, and many other configuration and runtime characteristics. The trade-off for the improved productivity, flexibility and reliability was the incompatibility of applications written in Mule 3 to the Mule 4 runtime.  Upgrading Mule 3 to Mule 4 applications would require them to be re-written.

Initially, upgrading from Mule 3 to Mule 4 may not have been a high priority for many customers, but as prior releases come out of support, the pressing need to migrate has become more apparent. Version 3.5 ended Standard Support in July of 2016, and Extended Support in January 2020 - see Support Policy here for more detail.  Those running a version 3.5 application in CloudHub are now no longer able to deploy it, or re-start their application as the runtime has been deprecated. Without migrating the application to a supported version, there is a serious risk to business continuity.

Migration Strategies

As mentioned earlier, it is not possible to simply “upgrade” a Mule 3 application and deploy it to Mule 4, the application has to be developed using the Mule 4 framework. Two strategies that can be employed when approaching the migration to Mule 4 are.

Migrate As Is

For some applications their value and function may be well known. They do what they need to do, and the way that they achieve it fulfills the requirements. They may be the sort of applications that do not provide the most innovative or differentiating capabilities, but are required for business continuity. For these applications, it may be appropriate to simply migrate them as is. No changes to the functionality, no changes architecturally, no changes to the technology methods employed. The aim being to provide like for like functionality from Mule 3 to Mule 4.

Enhance, Extend, Re-architect

Another strategy for migration is to take the opportunity to re-evaluate the application. Determine if it is still fit for purpose, could it be enhanced or extended to provide additional business benefits? Does it make sense to change or adapt the technology choices that were made years ago to incorporate new methods, effectively extending the life of the application? For example, enhancing a SOAP service to also provide a REST interface, or taking advantage of streaming capabilities for payload processing.

It might be worth considering re-architecting the application, and incorporating the lessons learned since it was developed to deliver a more stable, reliable, supportable, or performant application. The re-architecting also facilitates the incorporation of new technologies and approaches without having to jerry rig them in place.

Evaluating the application against the strategic direction of the organisation and the IT landscape that underpins it could yield opportunities to provide support for enhanced digital experiences. This could be achieved through expanded and consumer-focused APIs, as well as the adoption of new channels between the customer, partners, and the organisation.

Download the API Best Practices White Paper now!

Migrating the Application

There are two main ways to migrate the Mule 3 application to Mule 4:

  1. Manually re-develop the application either “as is” or in an enhanced or re-architected manner. Up until recently, this has been the only viable path to Mule 4 since it was released in 2018.
  2. Use the Mule 3 to Mule 4 migration tool, the Mule Migration Assistant to automate many parts of the application migration

Mule Migration Assistant

The Mule Migration Assistant is an open-source command-line migration tool developed by MuleSoft, to provide a level of automation in taking existing Mule 3 applications and creating Mule 4 applications. It can greatly reduce the amount of time required to perform the upgrade, however, it is important to note that it is not designed to do 100% of the work. It is always expected that manual remediation of the code is required, as there are many scenarios that an automation tool cannot accommodate. Common areas that will require attention include:

  • Where deprecated processors and components have been used. New Mule 4 processors will need to be selected and configured. For example:
    • splitters 
    • message enricher
    • filters
    • poll
    • transformer
    • validator
    • router
    • message-info-mapping
  • Constructs that do not directly translate into Mule 4 processors. The Migration Assistant is not able to understand the intent associated with the use of Mule 3 constructs with respect to translating them into Mule 4. An example of this is the Mule 3 Splitter and Aggregator. Splitters no longer exist in Mule 4, and the Aggregators possess very different behaviour.
  • Where Mule Expression Language (MEL) expressions cannot be automatically converted to DataWeave, such as procedural scripts.
  • Inbound and Outbound connector properties
  • Inbound and Outbound Attachments

The Mule Migration Assistant generates a report detailing the issues that were encountered and provides relevant links to further information on how to approach and remediate the issue. It also places the report comments and links within the Mule code itself, making it easy to review the application and address the issues.


Mule Migration Assistant

Fig: 1 - Mule Migration Assistant Report


Mule Migration Assistant Error Detail

Fig: 2 - Mule Migration Assistant, Error Detail

The assistant supports Mule 3.8 and 3.9 applications, but can still be used on older versions, however the amount of automation may be lower with high levels of manual remediation being required.


Migration Process at a Glance

The following steps for migrating the application with the Mule Migration Assistant will facilitate a smooth transition to Mule 4.

Understand The Application

Whilst on the surface it may appear obvious that a base level of understanding of what the application is trying to achieve, how it actually does it, and the reasons why it was constructed a certain way is required, when dealing with applications written long ago such knowledge may not be present with the current team members, or not at the forefront of mind. Reviewing the selected application for this level of understanding is key in later steps where the Mule Migration Assistant has not been able to directly map application processors to equivalent Mule 4 processors.

In reviewing and refreshing your knowledge of the application, look out for any known areas that the migration assistant does not address. This will provide a more realistic baseline for the post migration effort required. Areas to fully understand include 

  • Any groovy scripts
  • Mule Expression Language (MEL) scripts, and any other transformation logic. 
  • Look for any imported classes to groovy scripts for which you do not have or control the source code. Not being able to obtain the most recent versions of these classes, particularly if they are used in conjunction with any application connector (for example data types for a packaged COTS application), may result in significant re-working of these transformations.

Run The Mule Migration Assistant

Follow the simple instructions for running the migration assistant on the application. (See the Mule Migration Assistant Tutorial)

Address The Quick Fixes

The Mule Migration Assistant generates a detailed report of any issues or errors, items that require manual attention and intervention to complete the migration. A quick scan of this report will help you to identify the “quick fixes”, things such as simple one line changes, for example utilising the new variable accessors, or removing redundant code. You may well find that the majority of the migration issues were relatively straightforward to correct.  Again, this will depend upon the age and version of the source Mule application (older versions will generate more manual interventions).

Research Alternative Constructs

Some Mule 3 processors do not have a direct correlation to a Mule 4 processor, and it is in these situations you will need to manually choose the most appropriate combination of processors to replicate the desired functionality. This is where a clear appreciation of what the application is doing, how, and why from the “Understand the Application” step will be of value. One such situation is the Mule 3 Splitter and Aggregator. 

Other Post Migration Tasks

There are a number of post migration tasks that may be required, depending upon how the Mule 3 application is built and which components are used. While the Mule Migration Assistant does do some Mule Expression Language (MEL) to DataWeave conversion, there are a number of cases that it does not deal with, and these need to be manually remediated, as discussed in the Post Migration Tasks section of the documentation. Furthermore, the updating of inbound and outbound connector properties, along with session properties will also require manual attention to use the Mule 4 syntax and constructs for these variables.

Lessons Learned

Being forewarned is forearmed, and understanding what the Mule Migration Assistant will and will not do for you in the migration process will enable you to more accurately resource and schedule the applications for migration. It will allow you to categorise the applications that require little intervention and those that may require a high level of attention.

As time passes, source and target enterprise applications evolve, as do their methods and format for communication. Upgrading a connector to the current version can have impacts upon data transformation within the Mule application, and these changes are potentially time-consuming. If you have multiple Mule applications that interface to the same enterprise application, selecting one integration as a proof of concept can afford you the opportunity to encounter these issues, quantify the scale of the changes, and devise the appropriate approaches to resolve them. This will streamline the migration of subsequent Mule applications.

Talk to an API expert

Benefits of the Migration Assistant

The Mule Migration Assistant provides an accelerated path for taking Mule 3 applications to Mule 4. Not only does it do much of the heavy lifting of implementing the Mule 4 application, but it also reduces the risks associated with having to re-write the application from scratch. Having everything from the original application brought across into the Mule 4 application ensures that nothing is “missed” or “left behind”, providing for a greater level of surety to the quality of the migrated application.

The Mule Migration Assistant takes on many of the repetitive tasks associated with a migration, and frees up developers to focus on the valuable knowledge driven steps, providing not only a more efficient but also more expedient migration.

We hope you found this post useful.  If you're thinking about your API strategy or development, you might like our API Best Practices White Paper.

Reference Documents

Need help with MuleSoft? Whatever stage you’re at with MuleSoft, we make it easy for you to quickly deliver your MuleSoft integration projects.  Learn more.