Skip to content

Latest commit

 

History

History
525 lines (448 loc) · 20 KB

migration-tutorial.adoc

File metadata and controls

525 lines (448 loc) · 20 KB
Raw

Mule Migration Assistant Tutorial

Important

Mule Migration Assistant (MMA) is subject to the terms and conditions described for Community connectors. Additionally, Mule Migration Assistant is distributed under the terms of the 3-Clause BSD License.

This tutorial walks you through the main steps for migrating a Mule 3 app to Mule 4. It covers use of the MMA, the Migration report, and the Compatibility module.

Prerequisites

In addition to using the MMA, which initiates the migration to Mule 4, you also need to use two versions of Anypoint Studio. Studio 6 is compatible with Mule 3.x runtime versions. Studio 7 is compatible with Mule 4.x runtimes.

This tutorial uses Studio version 6.6.4 for the Mule 3 app and Studio 7.5.0 for the migrated Mule 4 app.

Step 1: Download and Import a Mule 3 App

Start by downloading a Mule 3 app from Anypoint Exchange, then importing it into Studio 6. In subsequent sections, you will migrate this app to Mule 4.

Exchange: Querying a MySQL Database

  1. Download version 1.4.0 of the Querying a MySQL Database (external link) asset from Exchange.

    Note that the 1.4.0 asset is a Mule 3 app that runs on Mule Runtime 3.x. Its filename is querying-a-mysql-database-1.4.0-mule-application-example.zip.

  2. In Studio 6, import the downloaded zip file by going to File → Import → Anypoint Studio generated Deployable Archive (zip), navigating to the zip file, and then clicking Finish.

    This process loads the app into a project in Studio 6. By default, the name of the project matches the zip filename (minus the file extension).

  3. Proceed to Step 2: Create a Mule 4 App from the Mule 3 App.

Step 2: Create a Mule 4 App from the Mule 3 App

Run MMA on the Mule 3 app. In subsequent sections, you will import the migrated app into Studio 7 and perform the manual steps needed to complete the migration to Mule 4.

  1. Unzip MMA mule-migration-assistant-runner-1.0.0.zip file that you downloaded in Prerequisites.

    The Zip file contains mule-migration-assistant-runner-1.0.0.jar and a /libs subdirectory with a number of MMA-related JAR files that provide MMA resources.

  2. In a command console, run MMA from the directory unzipped directory, and set -projectBasePath and -destinationProjectBasePath options.

    Example:
    $ java -jar mule-migration-assistant-runner-1.0.0.jar -muleVersion 4.3.0 -projectBasePath /Users/me/AnypointStudio/workspace-studio6/querying-a-mysql-database-1.4.0-mule-application-example -destinationProjectBasePath /Users/me/Downloads/querying-a-mysql-database-mule4

    Note that you must revise the directory paths in the command line example above to specify your local directories.

    To discover the -projectBasePath to the Studio 6 project, you can navigate to File → Switch Workspace → Other in Studio. To that path, you also need to append the name of the project, as shown in the example above. The -destinationProjectBasePath can be any local path. For details, see Command-line Options.

    Windows only:

    Note that if you are on a Windows machine and receive the message Exception: Cannot read mule project., try using forward slashes (/) for paths set in the projectBasePath and destinationProjectBasePath options. You should also try running the command through a standard Windows console.

    When MMA runs successfully, the console output looks something like this:

    $ ...
Executing migrator 1.0.0...
===============================================================================
MIGRATION ASSISTANT RUN SUCCESSFULLY
===============================================================================
Total time: 9.405 s
Migration report: /Users/me/Downloads/querying-a-mysql-database-mule4/report/summary.html

  3. Proceed to Step 3: Import the Migrated App to Studio 7

Step 3: Import the Migrated App to Studio 7

Import the migrated app into Studio 7. In subsequent steps, you will perform the manual procedure needed to complete the migration to Mule 4

  1. In Studio 7, import the generated Mule 4 app as a Studio project:

    1. Navigate to File → Import → Anypoint Studio/Anypoint Studio project from File System.

    2. Load the Project Root directory that contains the Mule 4 app.

    3. Click Open.

  2. Open the imported app in Studio 7.

    The app is in the querying-a-mysql-database-mule4 project. All the app’s components are in a single flow called database-to-jsonFlow.

    Imported App

  3. Proceed to Step 4: Perform Manual Migration Procedures

Step 4: Perform Manual Migration Procedures

Open and review the MMA-generated Mule Migration report, fix the issues it finds, and remove any unnecessary complexity that MMA adds to the app.

A migration report identifies items that remain to complete the migration to Mule 4. For the sample app, the migration report looks like this:

Mule Migration Assistant Report

The warnings (WARN messages) in this report are associated with components in the Compatibility module that you need to migrate manually before using the app in a production environment. A report can also contain errors (ERROR messages) that must be migrated manually before the app will work and INFO messages about Mule 3 components that were replaced by Mule 4 improvements or removed.

  1. In a web browser, open the Migration report (summary.html) produced by the MMA.

    You can find the path to the report at the bottom of the MMA’s console output, for example: /Users/me/Downloads/querying-a-mysql-database-mule4/report/summary.html.

  2. Address warnings and other messages in the report by performing these tasks:

When you complete the modifications, the flow will look like this:

Flow: Database To JSON

Migrate HTTP Listener Components

In Mule 3, connectors and transports that send outbound data must explicitly specify outbound properties, such as outgoing status code responses or headers for an HTTP listener.

The Migration report produces this warning twice within the HTTP listener component:

Migration WARN:
Avoid using an outbound property to determine the status code.

Because the Mule 3 sample app does not use the statusCode outbound property from the Mule 3 HTTP transport and because no outbound property is set in a flow, you can safely remove any use of the outbound property in this case.

  1. In Studio 7, delete these elements from the Configuration XML for the migrated app:

    <http:response statusCode="#[migration::HttpListener::httpListenerResponseSuccessStatusCode(vars)]">
  <!--Migration WARN: Avoid using an outbound property to determine the status code.-->
  <!--    For more information refer to:-->
  <!--        * https://github.com/mulesoft/mule-migration-assistant/blob/master/docs/user-docs/migration-tool-post-mig.adoc#outbound_properties-->
  <http:headers>#[migration::HttpListener::httpListenerResponseHeaders(vars)]</http:headers>
</http:response>
<http:error-response statusCode="#[vars.statusCode default migration::HttpListener::httpListenerResponseErrorStatusCode(vars)]">
  <!--Migration WARN: Avoid using an outbound property to determine the status code.-->
  <!--    For more information refer to:-->
  <!--        * https://github.com/mulesoft/mule-migration-assistant/blob/master/docs/user-docs/migration-tool-post-mig.adoc#outbound_properties-->
  <http:headers>#[migration::HttpListener::httpListenerResponseHeaders(vars)]</http:headers>
</http:response>

  2. Notice that MMA provided an HTTP Listener configuration above the <flow/> element in the XML configuration:

    <http:listener-config doc:name="HTTP Listener Configuration"
  name="HTTP_Listener_Configuration">
    <http:listener-connection host="localhost" port="${http.port}" />
</http:listener-config>

    You can define the property placeholder for the port in your project or (see Configure Property Placeholders, an external link) or use a port number (for example, port="8080").

  3. Proceed to Migrate the Attributes to Inbound Properties Component.

Migrate the Attributes to Inbound Properties Component

This component reads attributes of the Mule message and generates a Mule 3.x equivalent of inbound properties as a variable. Any use of an Inbound property in a migrated app requires you to replace references to an Inbound property with the Attributes object from the new Mule message.

Because there are no inbound properties in the querying-a-mysql-database-1.4.0-mule-application-example app, you can safely remove the Inbound Properties Component component from it.

The Migration report produces this warning for the Attributes to Inbound Properties component:

Migration WARN:
Expressions that query 'inboundProperties' from the message should instead
query the message 'attributes'. Remove this component if there are no uses of
'inboundProperties' in expressions or components that rely on
'inboundProperties' (such as 'copy-properties').-->

  1. Delete the Attributes to Inbound Properties component:

    <compatibility:attributes-to-inbound-properties>
  <!--Migration WARN: Expressions that query 'inboundProperties' from the
  message should instead query the message 'attributes'. Remove this
  component if there are no uses of 'inboundProperties' in expressions or
  components that rely on 'inboundProperties' (such as 'copy-properties').-->
    <!--    For more information refer to:-->
    <!--
    https://docs.mulesoft.com/mule-runtime/4.3/intro-mule-message#inbound-properties-are-now-attributes-->
</compatibility:attributes-to-inbound-properties>

  2. Proceed to Migrate Outbound Properties to var Component.

Migrate Outbound Properties to var Component

The migration report produces this warning for the two Outbound Properties to var components in the flow:

Migration WARN:
Instead of using outbound properties in the flow, move the expression that
sets the property into the XML attribute (such as 'method') of the operation
or listener that accepts the expression.

The XML element for the Outbound Properties to var component looks like this:

<compatibility:outbound-properties-to-var>
    <!--Migration WARN: Instead of using outbound properties in the flow,
      move the expression that sets the property into the XML attribute (such
      as 'method') of the operation or listener that accepts the
      expression.-->
    <!--    For more information refer to:-->
    <!--
    https://github.com/mulesoft/mule-migration-assistant/blob/master/docs/user-docs/migration-tool-post-mig.adoc#outbound_properties-->
</compatibility:outbound-properties-to-var>

  1. To understand this issue, double-click the Outbound Properties to var icon in the Message Flow view, and go to the Help tab in the configuration area.

    Outbound Properties to var

    This note indicates that the component is intended to emulate the use of outbound properties in a Mule 3 App. Because there are no outbound properties in the flow, it is safe to remove the components.

  2. Remove the both Outbound Properties to var components (<compatibility:outbound-properties-to-var /> elements) from the app.

  3. Proceed to Migrate the Global Database Connection.

Migrate the Global Database Connection

The Migration report produces this information about the global connector configuration element within Perform a query in MySQL component:

Migration INFO:
The config in Mule 3 is specific for an engine, but it contained an 'url'
attribute. It will be made generic in order to keep the URL.

MMA sets the global connector configuration to a Generic type to preserve the url attribute used in the Mule 3 app. However, because the app is using a MySQL database, you can change the global connection type and its settings to a MySQL Connection.

  1. Double-click the Perform a query in MySQL component to open its configuration tab.

  2. In the General tab, click the green plus sign (+) located to the right of the Connector configuration text field. (If you mouse over the +, you see the word Add.)

    Database Configuration: Opening Database Config Window

  3. In the Database Config window that opens, click the Connection field, and change the value from Generic Connection to MySQL Connection.

    Database Configuration: MySQL Connection

  4. To add the recommended JDBC driver for this database, click the Configure button and select Add recommended library to replace any existing driver.

    Database Configuration: Add Recommended Libraries

  5. If you have access to a MySQL server into which you can import a database, specify your Connection settings, and use company for the Database setting, for example:

    Database Configuration: Set Properties

    You can skip this step if you do not have access to a MySQL database server.

  6. Proceed to Migrate the Database Query to Mule 4, also for the Perform a query in MySQL component.

Migrate the Database Query to Mule 4

The Migration report produces this warning regarding inboundProperties settings within Perform a query in MySQL component:

Migration WARN:
Expressions that query inboundProperties from the message should instead query
the attributes of the message. Remove this component when there are no
remaining usages of inboundProperties in expressions or components that rely
on inboundProperties (such as 'copy-properties').

In this procedure, you replace the reference to the inbound property with a parameter called :lastname, then define a lastName input parameter as a reference to attributes.queryParams.lastName.

  1. In the General tab of the Perform a query in MySQL, delete the value of last_name in the Mule 3 SQL Query:

    #["select first_name from employees where last_name = '$(vars.compatibility_inboundProperties['http.query.params'].lastname)'"]

  2. Replace the deleted value of last_name with a parameter called :lastname:

    SELECT first_name FROM employees WHERE last_name = :lastName

    Be sure to remove the hash mark and square brackets (#[]).

  3. On the Input Parameters field, click the fx button, and specify the following in the text field:

    {'lastName' : attributes.queryParams.lastname}
    Perform A Query in MySQL

  4. Proceed to Review the Message on Streaming in Mule 4, also for the Perform a query in MySQL component.

Review the Message on Streaming in Mule 4

Mule 4 handles streaming differently than Mule 3, so the Migration report produces this message in the Perform a query in MySQL component:

Streaming is enabled by default in Mule 4

  1. Simply review the Enabling Streaming documentation.

    You do not need to perform any manual migration tasks in this case.

  2. Proceed to Replace the Convert Object to JSON Component.

Replace the Convert Object to JSON Component

MMA does not support the migration of the Object to JSON component to Mule 4.

To complete the migration, this procedure replaces the Convert Object to JSON transformer with a Transform Message component, sets the output type of the DataWeave script in the Transform Message component to JSON, and sets the script to the message payload.

  1. Delete the Convert Object to JSON transformer from the flow.

    <json:object-to-json-transformer doc:name="Convert Object to JSON" />

  2. In the Mule Palette, click Core, then locate and drag the Transform Message component to the same location in the flow.

  3. Double-click the Transform Message component to open the configuration area.

  4. In the Output section on the right, replace application/java and the curly braces ({}) with application/json and payload, like this:

    %dw 2.0
output application/json
---
payload

    The configuration should look like this:

    Transform Message

  5. Go to the Configuration XML view in Studio to verify that there are no remaining comments that contain WARN messages.

  6. By the end of the migration, the flow should look like this:

    Flow: Database To JSON

  7. Proceed to Step 5: Run and Test the Migrated App.

Step 5: Run and Test the Migrated App

After completing all the manual migration steps for the app, you can run and test that it works.

Prerequisites:

To be able to test the migrated app, you need a MySQL server into which you can import and query the employees database, and you need working database and HTTP listener connections.

  1. Run this script into your MySQL server: Sample MySQL Script

    This script creates a database called company with an employees table that contains data needed to test the SELECT query defined in Migrate the Database Query to Mule 4.

    One way to import the script is through the Data Import/Restore area of the MySQL Workbench tool using the Import from Self-Contained File field to point to the script.

    Alternatively, after logging into your MySQL server on a Mac (for example, with mysql --user=root -p), you might run this command to run the script: mysql> source /usr/local/mysql/bin/create.sample.db.sql

  2. In Studio, test your Connection to the MySQL database.

    You test the connection from dialog that opens when you click to edit the Connector config in the Perform a query in MySQL component.

    Make sure the connection is successful before proceeding to the next step.

  3. Now test your Connection to the HTTP listener from the Receive HTTP request component.

    Make sure the connection is successful before proceeding to the next step.

  4. Make sure your app is running in Studio.

    You can right-click the canvas in Studio and select Run project to run the app.

    You need to check the Console in Studio to make sure the app deploys successfully before proceeding to the next step.

  5. In a web browser or app such as Postman, go to URL (such as http://localhost:8080/?lastname=Howard) that uses your HTTP listener configuration, and view the JSON results:

    [
  {
      "first_name": "Devin"
  },
  {
      "first_name": "Luke"
  }
]

    Notice that the URL includes query parameters defined in the HTTP listener configuration.

Note that you can also download and import the Mule 4 version of Querying a MySQL Database app for Mule 4 (external link) from Exchange and compare your results.