Migration Studio

improve this page | report issue

Mobile Foundation Migration Studio

Download the Mobile Foundation Migration Studio.

What is Migration Studio

Mobile Foundation Migration Studio plugin is an Eclipse plugin that does an in-place upgrade of hybrid projects on MobileFirst Platform Foundation v7.1, enabling them to connect to a Mobile Foundation v8 server. This plugin is similar to the MobileFirst v7.1 Studio plugin and can be installed on the same supported environments as MobileFirst Platform Foundation v7.1 Studio.

Why use the Migration Studio

Mobile Foundation Migration Studio plugin provides a quick path for enabling the upgrade of existing MobileFirst Platform Foundation v7.1 hybrid apps, so that they work with Mobile Foundation v8.

Mobile Foundation Migration Studio does a limited migration to Mobile Foundation v8, so the standard migration approach should be the preferred approach.

Compare migration using the Migration Studio with the standard migration approach

The standard migration approach on a MobileFirst Platform Foundation v7.1 hybrid app as described in the Migration Cookbook will result in a full fledged Cordova app that connects to a Mobile Foundation v8 server. The Migration Studio approach, however, will retain the legacy hybrid structure of the app (i.e. a MobileFirst project with an embedded Cordova plugin). Due to this reason, the apps that are migrated using the Migration Studio will not have the full spectrum of capabilities available to a traditional Mobile Foundation v8.0 app. See this section for a full list of known limitations. 

Get started with Migration Studio

To get started with Migration Studio, you need to carry out the following tasks.

  • Task 1: Set up your project.

    Execute the following steps to complete this task.

    1. Install a version of Eclipse that is supported by MobileFirst Platform Foundation v7.1 Studio plugin.

    2. Download the Migration Studio and install the plugin on to your Eclipse IDE. This step is no different from installing MobileFirst Platform Foundation v7.1 Studio plugin.

      Important: Do not do an in-place upgrade over an existing MobileFirst Studio installation.

    3. Import your MobileFirst Platform Foundation v7.1 project into the Mobile Foundation Migration Studio using the File > Import > File System option. Alternatively, if you have the project already exported and in your file system, you can import the exported .zip file.  You will notice that the Migration Studio interface is very similar to the MobileFirst Platform Foundation v7.1 Studio.

    4. Retain a backup of your environment folders (android, iphone, ipad). Open the application-descriptor.xml and delete the environments. Choose the option to delete all workspace resources. Set up your project

    5. Add the environment(s) to your project again and wait for the build to complete. At this step, if your earlier project had any customizations (for example, adding a custom Cordova plugin) done to the native project, you will have to repeat them here.

      The Migration Studio upgrades the version of Cordova within the project, and therefore, some existing third-party Cordova plugins may not be compatible with the new version of Cordova. If so, check for an update available to your plugin and update the Cordova plugin to the appropriate version.

  • Task 2: Set up your application.

    Execute the following steps to complete this task.

    1. Custom Challenge handlers will be modified to work with the challenge handler framework of Mobile Foundation v8. However, you will have to modify the challenge handler’s createChallengeHandler method and the response that is submitted for the challenge to suit the Mobile Foundation v8.0 security check. 7.1 app
       var loginChallengeHandler = WL.Client.createChallengeHandler("UserLoginRealm");
       options.parameters = {
               j_username : $('#AuthUsername').val(),
               j_password : $('#AuthPassword').val()

      Migrated app

       var loginChallengeHandler = WL.Client.createChallengeHandler("UserLoginSecurityCheck");
       options.parameters = {
               username : $('#AuthUsername').val(),
               password : $('#AuthPassword').val()

      Note: The parameters and the name depends on how you configure your security check.

    2. [Optional] If you have multiple html pages in your app, edit each html file and edit the path references to the JavaScript and CSS files to work with the new project.
  • Task 3: Configure Mobile Foundation v8.0.

    Execute the following steps to complete this task.

    1. Start the Mobile Foundation v8 server (use either the Mobile Foundation v8 DevKit server or an OpenShift Container Platform installation of Mobile Foundation or a traditional on-premise installation of Mobile Foundation) and register your app on the Mobile Foundation v8 server. More details on registering the v8 Cordova apps is here.

    2. Migrate your adapters and authentication or login modules and deploy them to your Mobile Foundation instance. For more information on migrating adapters, see this section.

  • Task 4: Run your application.

    Execute the following steps to complete this task.


    1. Open Android Studio (3.2 or higher).
    2. Click Open an existing Android Studio Project and navigate to the folder Eclipse Workspace/<ProjectName>/apps/<AppName>/android/native.
    3. Accept any prompts to recreate the gradle wrapper, upgrade or change the version of gradle wrapper and any prompts to clear the read-only status of the files.
    4. Navigate to the mfpclient.properties file in the Project view and modify the server connection parameters.
    5. Run the project. If required, change the version of the compileSdk and build tools in the build.gradle file.
    6. If you are using Push Notifications, you will have to generate a google-services.json file and replace it in the project. For more information, read this blog post


    1. Using XCode, open the iOS native project found in Eclipse_Workspace/<ProjectName>/apps/<AppName>/iphone/native.
    2. Navigate to the mfpclient.plist file in the Project view and modify the server connection parameters.
    3. If your application is using Push Notifications feature, enable Push Notifications capability in Xcode project settings and add a valid provisioning profile. See here, for more details.
    4. No additional configuration is required for iOS, you can run the project from XCode.

      Follow the same steps if you have an iPad environment.

    Note: For all the environments(Android, iOS and iPad) the static_app_props.js (www/default/plugins/cordova-plugin-mfp/worklight) file has to be modified with the application details such as version, package name or bundle identifier before building and running the app.

Known limitations of Migration Studio

  • Migration Studio only upgrades Android, iPhone and iPad environments. Other environments are not upgraded. 
  • Preview is not supported by this plugin.
  • Migration Studio upgrades the embedded version of cordova-android to 8.1.0 and cordova-ios to 5.1.1. This version is fixed and cannot be modified.
  • Only the default skin is supported.
  • You will not be able to publish direct update packages to the MobileFirst server with this project.
  • JSON Store APIs are not yet supported in this release.

    Note: JSON Store can still be used by manually adding the files to the project i.e., adding cordova-plugin-mfp-jsonstore to the plugins folder, adding the plugin reference to the cordova_plugins.js file, and attaching the required JAR/Framework files.

  • New capabilities of Mobile Foundation v8.0 are not supported.
  • APIs that are deprecated or discontinued will have modified behaviour. See the following section for details on the change in behaviour.

Migrating applications using JSONStore

Migration of JSONStore plugin from applications using JSONStore is not automated in Migration Studio. Perform the following steps to manually migrate the JSONStore projects.

Download the cordova-plugin-mfp-jsonstore from here.

For Android

  1. Copy the following cordova-plugin-mfp-jsonstore/bootstrap.js file and cordova-plugin-mfp-jsonstore/worklight  folder to <ProjectName>/apps/<AppName>/android/native/<ProjectName><AppName>android/src/main/assets/www/default/plugins/cordova-plugin-mfp-jsonstore folder.

  2. Open the <ProjectName>/apps/<AppName>/android/native/<ProjectName><AppName>android/src/main/assets/www/default/cordova_plugins.js  file and add the following entry for JSONStore in the module.exports array.
          "id": "cordova-plugin-mfp-jsonstore.jsonstore",
          "file": "plugins/cordova-plugin-mfp-jsonstore/bootstrap.js",
          "pluginId": "cordova-plugin-mfp-jsonstore",
          "runs": true
  3. Copy the dependencies(JAR files only) from the downloaded cordova-plugin-mfp-jsonstore/src/android/libs to the <ProjectName>/apps/<AppName>/android/native/<ProjectName><AppName>android/libs` folder and add these entries to the/apps//android/native/android/build.gradle` file dependencies section.
    compile files('libs/commons-codec.jar')
    compile files('libs/guava.jar')
    compile files('libs/jackson-core-asl.jar')
    compile files('libs/jackson-mapper-asl.jar')
    compile files('libs/ibmmobilefirstplatformfoundationjsonstore.jar')
    compile files('libs/sqlcipher.jar')
  4. Add the following entry to <ProjectName>/apps/<AppName>/android/native/<ProjectName><AppName>android/src/main/res/config.xml file.
    <feature name="StoragePlugin">        
    <param name="android-package" value="com.worklight.androidgap.jsonstore.dispatchers.StoragePlugin" />    

For iOS

  1. Copy the following cordova-plugin-mfp-jsonstore/bootstrap.js file and cordova-plugin-mfp-jsonstore/worklight folder to <ProjectName>/apps/<AppName>/iphone/native/www/default/plugins/cordova-plugin-mfp-jsonstore folder.

  2. Open the <ProjectName>/apps/<AppName>/iphone/native/www/default/cordova_plugins.js file and add the following entry for JSON Store in the module.exports array.
          "id": "cordova-plugin-mfp-jsonstore.jsonstore",
          "file": "plugins/cordova-plugin-mfp-jsonstore/bootstrap.js",
          "pluginId": "cordova-plugin-mfp-jsonstore",
          "runs": true
  3. Copy the framework from the downloaded cordova-plugin-mfp-jsonstore /src/ios/Frameworks/IBMMobileFirstPlatformFoundationHybridJSONStore.framework to<ProjectName>/apps/<AppName>/iphone/native/Frameworks folder and add it to the XCode’s Frameworks, Libraries and Embedded Content in the general tab.

    Note: Don’t replace the SQLCipher framework that is already present in the XCode project.

Use of deprecated or discontinued APIs

The following APIs have been discontinued and will have to be manually replaced with alternatives.  Visit this documentation to learn about the replacements.


The following APIs are no longer supported but an error message is displayed on the console when called.

WL.Client.close (android only)
WL.Toast.show (android only)


Mobile Foundation Migration Studio is an add-on made available for easy migration from MobileFirst Platform Foundation v7.1 to Mobile Foundation v8.0. The regular IBM support process of opening a case on the IBM Support portal does not apply for any issues related to the Migration Studio. For support, raise a request to join our Slack channel or open a GitHub issue.

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on June 01, 2020