Mule 3 to Mule 4 Migration Tool: Real-Time API

MuleSoft version 4 was released in May 2018 as part of the Titan release. It is recommended to write all new applications in Mule 4 unless you have a very strong reason for continuing with Mule 3. Mule 3 version will reach the end of life as per this schedule. So you can postpone the migration, but you cannot avoid it. The migration tool will help save manual migration efforts.

MuleSoft has released a beta version of a migration tool (Mule Migration Assistant). This tool will have to be used with the command line utility.

The GA version of the migration tool is not out yet. It will be integrated within Anypoint Studio itself. Let's try to convert a real-time Mule 3 application into Mule 4 using the tool. The Mule 3 API that we are trying to migrate is a Sys API that would connect to Uber to get order details. I have added the GitHub link to both Mule 3 and Mule 4 projects at the bottom of this article.

The migration tool creates Mule 4 project structure. It updates the POM file. It not only migrates the application files, but it also tries to migrate the Munit files.

Prerequisites

1. Java 1.8 or above

2. Anypoint Studio 6

3. Anypoint Studio 7

4. Migration tool JAR file

5. Convert Datamapper to Dataweave (as Datamapper is not supported by tool)

Let us see what steps are needed to migrate the project.

Download the migration tool JAR from here. You need to unzip it to a folder. This contains a JAR file and there are dependent libraries in /libs folder. Following command needs to be run.

java -jar mule-migration-assistant-runner-0.5.1.jar -muleVersion 4.1.5

-projectBasePath <<mule 3 project path> > -destinationProjectBasePath

<< mule 4 project path>> >

e.g.

There is an option to choose a Mule version for migration. I have given the 4.1.5 version. Make sure that the folder in the destination path is not available before running the command, as the tool will create it for you. The report is available for you to view in the newly created folder.

The issues shown under "Errors" must be resolved before running the application.

The issues shown under "Warnings" will let you run the API, but they must be replaced with Mule 4 components before moving to deployment. Mule adds compatibility modules that let some features from Mule 3 run in Mule 4.

The issues shown under "Info" are the messages about the Mule 3 features that were removed or changed after migration. These messages should be removed in Mule 4 API.

Let's import the migrated project in Anypoint Studio 7. The first change you will notice while importing the project in Studio 7 is there is no option to import the project by pom.xml file. You can import either via File System or via .jar file. In our case, we will use the former option.

In the XML view, you would see that the tool nicely adds comments about what issues were identified during migration.

Let's observe if pom.xml file has been properly migrated. You would notice that the properties section is copied as is from the old file to the new one. Make sure you remove unnecessary properties. Also, the Mule 3 dependencies are copied in the new file. These also need to be removed manually. After correcting the pom.xml file, let's see the report and fix the issues.

We would have to manually resolve the "Errors" issues. In our case, the following are the errors shown in the report.

As per the message, it tells about custom types not supported in Studio 7. This gets deleted in new API codebase. On close inspection, we can see that in Dataweave there is "metadata:id" tag. In Mule 4, there is another mechanism to identify metadata associated with different components. It is represented by "doc:id". The mapping for the same resides in application-types.xml file in src/main/resources folder. In Mule 4, you will have to manually add this metadata mapping.

The next issue talks about not supporting Spring specific attributes.

In the migrated project, we can see that "context:property-placeholder" gets changed to "configuration-properties" and the property ignore-unresolvable="true" gets removed. The mule-app.properties file does not exist in Mule 4. so it is treated as a configuration property. Instead of keeping this file, it is better to move its contents either to property file or runtime properties.

Let's move to "Warning" issues.

As we see here, most of the issues are because MEL could not be migrated to Dataweave expression. It also talks about removing inbound and outbound properties, as they are no longer supported in Mule 4. Other error talks about some properties that do not exist in Mule 4.

Another interesting observation I noted is in Mule 3 API, we can access the URI parameters before API kit router, but this is not the case in Mule 4. We create variables by accessing URI parameters before API kit router but this needs to be done after API kit router in case of Mule 4 APIs.

I will list down the changes that were done manually.

Mule 4 supports Munit version 2.x.x where as Mule 3 supported 1.3.x and lower. The migration tool will try to migrate the test cases, but some issues need to be resolved manually.

In the new version of Munit, add mocks and spies in the Behaviour section. Set event and flow reference to API in the Execution section while assertions or verifications can be added in the Validation section.

We will mock the backend call. Use "Set Event" to pass URI params. DW to set variables. A flow reference to call the API and add an assertion to validate the response.

Both Mule 3 and Mule 4 projects can be downloaded and verified from the below URL:

https://github.com/gunjand04?tab=repositories

Thanks for reading and please let me know if you have any questions.