Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (4.8)
  3. Mule 4 for Mule 3 Users
  4. Migration to Mule 4
  5. Migrating API Gateways

  6. Migrate API Proxies

Migrating API Proxies

Performing a Proxy Migration

To perform a proxy migration, this example uses the Mule Migration Assistant (MMA). The procedure requires that you meet the Prerequisites for the tool. For complete user documentation on MMA, see Migration to Mule 4 (on GitHub).

The MMA command for migrating proxies uses the standard command-line options (on GitHub) for migrating a Mule app:

Command-line Invocation:
$ java -jar mule-migration-assistant-runner-0.5.1.jar \
 -projectBasePath /Users/me/AnypointStudio/workspace-studio/my-mule3-proxy/ \
 -muleVersion 4.1.5 \
 -destinationProjectBasePath /Users/me/my-dir/my-migrated-proxy

Note that the MMA creates the directory for the migrated project through the -destinationProjectBasePath option. The my-migrated-proxy must not exist before you invoke the command. If you point to a folder that exists already, the migration will fail an error like this: Exception: Destination folder already exists.

When the migrator runs successfully, you see a message something like this:

Successful Migration
Executing migration...
...
========================================================
MIGRATION SUCCESS
========================================================
Total time: 11.335 s
Migration report:
/Users/me/my-dir/my-migrated-proxy/report/summary.html

After migration completes successfully, the destination folder contains:

  • A proxy POM file.

  • The report directory containing the Mule Migration Report (on GitHub) (summary.html). Note that the same information provided in the report can be found as comments in the proxy XML file.

  • The mule-artifact.json file, with a minMuleVersion value that matches the -muleVersion value set in the MMA command.

  • The src directory, which contains the migrated content.

The src directory contains subdirectories main and test. Inside main, the mule directory is the proxy XML file. At the same level as the mule directory, MMA will create a resources directory for any DataWeave files or other files that the migrated proxy needs. Note that the configuration file defined in the proxy XML must be present in the resources directory for the artifact to be deployed correctly. The test directory contains test configuration files.

After a successful migration, you need to modify the POM file as explained in POM Migration. Once the POM file has the correct organization ID, you can compile with mvn clean install. If the compilation is successful, you can upload the migrated proxy to Exchange using maven clean deploy. You can find a more detailed explanation of uploading a custom app in Publish and Deploy Exchange Assets Using Maven.

POM Migration

The POM file migration modifies the file to include the elements necessary for uploading the custom proxy to Exchange.

After the migration:

  • Replace the {orgId} value in the <groupId/> and <exchange.url/> elements with the organization ID found in Anypoint Platform.

For more information on how to obtain the organization ID, see Uploading a Custom Policy to Exchange.

By default, the Exchange URL is set to the production environment.

<groupId>{orgId}</groupId>

<properties>
 <exchange.url>https://maven.anypoint.mulesoft.com/api/v1/organizations/{orgId}/maven</exchange.url>
</properties>

Note that for the EU version of the URL, you need to set the URL manually after the migration:

  • URL template for EU: https://maven.eu1.anypoint.mulesoft.com/api/v1/organizations/{orgId}/maven

If the MMA does not find a POM file for the proxy, MMA will create a new POM file. In this file, the artifactId for the proxy is the name of the base directory for the proxy app. For example, for a proxy in mytestproxy/src/main/app/proxy.xml, the artifactId is mytestproxy.

Dependency and Plugin Versions

Dependency and plugin versions are set by default by the MMA, and you can change them manually, as needed.

Un-Migrated Elements

Several elements are not migrated from Mule 3 to Mule 4:

Element Reason

api-platform-gw:tags

API auto-create is disabled in Mule 4.

api-platform-gw:description

API auto-create is disabled in Mule 4.

For each of these elements, the child elements are removed, as well.

Common Migration Issues

If proxy files are not found during the migration, the MMA prints a message like this one:

Unsuccessful Migration
Executing migration...
...
===============================================================================
MIGRATION FAILED
===============================================================================
Total time: 3.008 s
Exception: Cannot read mule project. Is it a Mule Studio project?
com.mulesoft.tools.migration.engine.exception.MigrationJobException: Cannot read mule project. Is it a Mule Studio project?
	at com.mulesoft.tools.migration.engine.project.MuleProjectFactory.getMuleProject(MuleProjectFactory.java:50)
	at com.mulesoft.tools.migration.engine.MigrationJob.generateSourceApplicationModel(MigrationJob.java:116)
	at com.mulesoft.tools.migration.engine.MigrationJob.execute(MigrationJob.java:80)
	at com.mulesoft.tools.migration.MigrationRunner.main(MigrationRunner.java:83)

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

POM Migration Issues

If the MMA does not find the POM model for the proxy, the MMA will either generate the model from an existing POM in Mule 3, or if there is no Mule 3 POM, the MMA will create the model. If MMA uses an existing POM, any incorrect POM definition that the MMA encounters will cause POM model creation process to fail. For information about a POM model failure, you need to check for any preceding error messages regarding MMA steps on modifying the POM model.

RAML Proxy Migration

RAML proxy elements are migrated to REST proxy elements:

Mule 3 Mule 4

proxy:raml-proxy-config.

rest-validator:config.

proxy:raml.

rest-validator:validate-request.

apikit:mapping-exception-strategy.

error-handler with on-error-continue elements in the flow containing the rest-validator:validate-request element.

The error-handler element contains the following types for on-error-continue elements:

Type Status Code

REST-VALIDATOR:BAD_REQUEST

400

REST-VALIDATOR:RESOURCE_NOT_FOUND

404

REST-VALIDATOR:METHOD_NOT_ALLOWED

405

HTTP:TIMEOUT

504

Exceptions that are not found in the Mule 3 element are autocompleted by the Mule Migration Assistant.

WSDL Proxy Migration

WSDL proxy migration consists of migrating the attribute values for WSDL properties. In Mule 3, most values are extracted using the function defined as attribute value. In Mule 4, there is no equivalent process, so most properties are migrated to a default value and require manual configuration with values from the WSDL file, which start with the service keyword.

Some properties are renamed to extract the value in a more transparent way, for example:

Mule 3 Mule 4

![wsdl(p['wsdl.uri']).services[0].preferredPort.name]

${service.port}

![wsdl(p['wsdl.uri']).targetNamespace]

${service.namespace}

![wsdl(p['wsdl.uri']).services[0].name]

${service.name}

Other properties, such as the following, are migrated to a DataWeave expression that uses the WSDL Functions Extension dependency, provided by MMA, to extract the expected values:

Mule 3 Mule 4

![wsdl(p['wsdl.uri']).services[0].preferredPort.addresses[0].port]

#[Wsdl::getPort('${wsdl.uri}','${service.name}','${service.port}')]

![wsdl(p['wsdl.uri']).services[0].preferredPort.addresses[0].host]

#[Wsdl::getHost('${wsdl.uri}','${service.name}','${service.port}')]

![wsdl(p['wsdl.uri']).services[0].preferredPort.addresses[0].path]

#[Wsdl::getPath('${wsdl.uri}','${service.name}','${service.port}')]

See Also

Migrating API Gateways

Migrating API Gateways: Autodiscovery

Migrating API Gateways: Mule Runtime Configuration

Core Components Migration

Publish and Deploy Exchange Assets Using Maven