For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.


Starting the Cordova app migration with the migration assistance tool

The migration assistance tool helps you prepare your cross-platform apps that were created with earlier versions of IBM MobileFirstâ„¢ Platform Foundation for migraiton by identifying APIs that are no longer valid and copying the projects into Cordova apps that are supported by version 8.0.


Before you begin

The following information is important to know before you use the migration assistance tool:


Overview

Cross-platform apps that were created with earlier versions of IBM MobileFirst Platform Foundation commands or the Cordova with IBM MobileFirst Platform Foundation commands are not supported in version 8.0 without some changes. The migration assistance tool simplifies the process with the following functions:

The migration assistance tool does not modify or move any developer code or comments of your app. You must continue the migration process with either Completing migration of a MobileFirst hybrid app or Completing migration of a MobileFirst Cordova app after you run this tool.


Procedure

  1. Download the migration assistance tool by using one of the following methods:
  2. Install the migration assistance tool.
    1. Change to the directory where you downloaded the .tgz file.
    2. Use NPM to install the tool by entering the following command:

      npm install -g tgz_filename

  3. Scan and copy the IBM MobileFirst Platform Foundation app by entering the following command:

    mfpmigrate client --in source_directory --out destination_directory

    source_directory
    The current location of the initial project.
    destination_directory
    The directory where the new version 8.0 compatible Cordova structure is output.
    When it is used with the client command, the migration assistance tool completes the following actions:

    • Identifies APIs in the existing IBM MobileFirst Platform Foundation app that are removed, deprecated, or changed in version 8.0.
    • Creates a Cordova structure based on the structure of the initial app.
    • Copies or adds the following items, when applicable:

      • Android operating system
      • iPhone and iPad operating system
      • Windows operating system
      • Cordova-mfp-plugin
      • Cordova-plugin-mfp-jsonstore plug-in, if the JSONStore feature was installed on the old project.
      • Cordova-plugin-mfp-fips plug-in, if the FIPS feature was installed on the old project.
      • Cordova-plugin-mfp-push plug-in, if the push notification feature was installed on the old project.
      • Hybrid certificates, if certificate pinning was enabled on the old project.
      • Application, script, and XML files

      Important: The migration assistance tool does not copy developer code or commented text into the new structure.

  4. Resolve the API issues in the new Cordova app.
    1. Review the api-report.html file that is created in the destination_directory directory. Each row of the table in this file identifies a deprecated, changed, or removed API that is used in the app that is not compatible with version 8.0. This file also specifies the replacement for removed APIs, when one is available.

      Table 1. Example of a table in the api-report.html file
      File path Line number API Line content Category of API change Description of change with instructions about how to resolve the API change.
      c:\local\Cordova\www\js\index.js 15 Wl.Client.getAppProperty document.getElementById('app_version') textContent=WL.Client.getAppProperty("APP_VERSION"); Not supported Removed from 8.0. Use Cordova plug-in to get app version. No replacement API. More information.
    2. Address the API issues that are identified in the api-report.html file.
  5. Manually copy the developer code from the initial app structure into the correct location in the new Cordova structure. Copy the content in the following directories, according to the type of the source IBM MobileFirst Platform Foundation app:
    IBM MobileFirst Platform Foundation hybrid app
    Copy the contents of the common directory of the source app to the www directory in your new Cordova app.
    Cordova with IBM MobileFirst Platform Foundation app
    Copy the contents of the www directory of the source app to the www directory in your new Cordova app.
  6. Run the migration assistance tool with the scan command on your new app to confirm that your API changes are complete.
    1. Enter the following command to run the scan:

      mfpmigrate scan --in source_directory --out destination_directory --type hybrid

      source_directory
      The current location of the files to scan. In an IBM MobileFirst Platform Foundation hybrid app, this location is the common directory of your app. In an IBM MobileFirst Platform Foundation version 8.0 Cordova cross-platform app, this location is the www directory.
      destination_directory
      The directory where your scan results are output.
      scan_type
      The type of project to scan.
    2. Address any remaining API issues that are identified in the api-report.html file.
  7. Repeat step 6 to run the scan tool on the new Cordova app until all of the issues are resolved.


What to do next

Complete the migration by completing the steps in one of the following topics, depending on the type of app that you are migrating:

Parent topic: Migrating existing hybrid or cross-platform apps to Cordova apps supported by MobileFirst version 8.0