MobileFirst Foundation 8.0 Migration Cookbook

improve this page | report issue

Overview

The purpose of this cookbook is to provide a clear and simple view of the migration steps for applications and adapters from IBM Worklight Foundation 6.2 or IBM MobileFirst Platform Foundation 6.3 - 7.1, to IBM Mobile Foundation 8.0.

The migration process guides you through the steps to transform classic hybrid applications into standard Cordova applications, and to update the MobileFirst SDK in native applications. Mobile Web apps are handled, too. Adapters are migrated into Maven projects, and implementation concepts such as the MobileFirst security framework, push notifications, and direct update are further clarified.

To ease some aspects of the migration process, a Migration Assistance tool is provided.
The tool helps you by identifying areas in your codebase that you will need to inspect and alter, such as APIs that are deprecated, no longer supported, or modified.

Note: This cookbook does not attempt to cover all possible migration scenarios and you are advised to visit the migration user documentation topics for a comprehensive read.

Getting Help

The Mobile Foundation team is glad to help with any questions you might have.
For official support, open a PMR. You can also ask questions over at StackOverflow and in our Slack community.

Quick Start

Before getting started with migrating your applications and adapters, and in case you haven't already, it is recommended that you go through the Quick Start tutorials to get familiar and experience Mobile Foundation 8.0.

More information is provided in the tutorials about topics such as registering applications, building and deploying adapters, implementing and configuring security and authentication, and lots more.




Setup and Tools

Before migration can begin, you need a running MobileFirst Server instance and the Migration assistance tool.

MobileFirst Server

You can set up a MobileFirst Server on IBM Cloud by using the Mobile Foundation IBM Cloud service. Alternatively, you can use the MobileFirst Developer Kit to set up a server that runs locally.

Migration Assistance tool

After the MobileFirst Server is up and running, and because you will use the Migration Assistance tool later on, first install the tool.

  1. Install node v6.x and npm v3.x as it is a prerequisite for the tool to work.
  2. From the MobileFirst Operations Console, click on the Download Center link at the bottom of the sidebar navigation. Follow the instructions to install the Migration Assistance tool, either from NPM or by downloading a .zip file.
Download the migration tool from the MobileFirst Operations Console


Migrating Applications

The steps to migrate your classic hybrid/MobileFirst Cordova, Web, and native applications include: assessing API changes by running the Migration Assistance tool, setting up the project structure, managing the application source, using package managers, and handling API changes.

Classic Hybrid Applications

In past releases, classic hybrid applications were created, developed, built, and managed by using the MobileFirst Studio plug-in for Eclipse or MobileFirst CLI. Starting with Mobile Foundation 8.0, support is introduced for standard Cordova applications, replacing the previous application model.

You create Cordova applications by using standard community tools, such as the Cordova CLI. The MobileFirst Cordova SDK is added to the mixture using the Cordova CLI as a set of Cordova plug-ins, which are available from npm.

The move to standard Cordova applications opens the door for developers to use their favorite tools and their own approaches to application development. As a developer, you are now empowered with the Cordova ecosystem.

Tip: You can also set up Eclipse for Cordova application development.

Learn more about Cordova application development.

Step 1

Open a command-line window and use the Migration Assistance tool in the following manner.

  • To only scan the classic hybrid project and have an API report generated, use:
    mfpmigrate scan --in path_to_source_directory --out path_to_destination_directory
  • To scan the classic hybrid project and create a predefined Cordova project, use:
    mfpmigrate client --in path_to_source_directory --out path_to_destination_directory [--projectName location_of_project]
    Note: This action might take a while to complete, depending on your Internet connection, because the process includes downloading the MobileFirst Cordova SDK plug-ins.
  • Replace source_directory with the path to the application folder located in application folder of the Studio project, for example: ../Desktop/InvokingAdapterProcedures/apps/InvokingAdapterProcedures
  • Replace destination_directory with a path to a folder that will house the converted application and the generated API report.
  • Replace location_of_project with a directory name of where you want the project created inside of the destination_directory. This flag is optional.
Migrate a Classic Hybrid app to a standard Cordova app

After the Migration Assistance tool has run successfully, you can observe the following effects:

  • The MigratedProject folder now contains a new Cordova application with the same metadata as your classic hybrid app (the application identifier and other settings that depend on the setup of the classic hybrid app), installed the MobileFirst Cordova SDK, and added the required platforms.
  • If the client command was used, an API report, {app-name}-api-report.html, was generated and opened in your default browser. It contains potential actions that you will need to follow to align the application implementation for use in Mobile Foundation 8.0.
API report

Step 2

Before you can act on the generated API report, you must copy the application source code over from the classic hybrid app to the Cordova app.

Classic hybrid app

Copy the contents of the common folder and paste it to the www folder of the Cordova app (replace if prompted).

MFPF 7.1 Cordova app

Copy the www folder and replace the existing www folder of the Cordova app.

Note: If you have environment-specific implementation in your classic hybrid app, you can copy it over by using Cordova Merges.

You are not required to use the Cordova application that is created for you by the Migration Assistance tool. Using the Cordova CLI, you can create a new Cordova application on your own and add the MobileFirst Cordova SDK, and any 3rd-party Cordova plug-in you might need. Follow the Cordova tutorials to learn more.

Step 3

With the application's source code now in the Cordova app, you must now add or edit a few code blocks.

  1. Update the www/index.html file.
    • Add the following CSS code to the head of your index.html file, before the CSS code that is already there.
      <link rel="stylesheet" href="worklight/worklight.css">
      <link rel="stylesheet" href="css/main.css">
      Note: The worklight.css file sets the body attribute to relative. If this affects the style of your app, declare a different value for the position in your own CSS code. For example:
      body {
        position: absolute;
      }
    • Add a reference to the Cordova JavaScript file to the head of the file after the CSS definitions.
      <script type="text/javascript" src="cordova.js"></script>
    • Remove the following line of code if it is present.
      <script>window.$ = window.jQuery = WLJQ;</script>
      You can download your own version of JQuery and load it as shown in the following code line.
      <script src="lib/jquery.min.js"></script>
      You do not have to move the optional jQuery addition to the lib folder. You can move this addition anywhere you want, but you must correctly reference it in the index.html file.
  2. Update the www/js/InitOptions.js file to call WL.Client.init automatically.
    • Remove the following code from InitOptions.js. The function WL.Client.init is called automatically with the global variable wlInitOptions.
      if (window.addEventListener) {
        window.addEventListener('load', function() { WL.Client.init(wlInitOptions); }, false);
      } else if (window.attachEvent) {
        window.attachEvent('onload',  function() { WL.Client.init(wlInitOptions); });
      }
  3. Optional: If you need to run logic before the MobileFirst framework is initialized, update the www/InitOptions.js file to call WL.Client.init manually.
    • Edit the config.xml file and set the mfp:clientCustomInit element's enabled attribute to true.
    • If you are using the MobileFirst hybrid default template, replace this code:
      if (window.addEventListener) {
        window.addEventListener('load', function() { WL.Client.init(wlInitOptions); }, false);
      } else if (window.attachEvent) {
        window.attachEvent('onload',  function() { WL.Client.init(wlInitOptions); });
      }
      with the following code:
      if (document.addEventListener) {
        document.addEventListener('mfpready', function() { WL.Client.init(wlInitOptions); }, false);
      } else if (window.attachEvent) {
        document.attachEvent('mfpready',  function() { WL.Client.init(wlInitOptions); });
      }

Step 4

The Cordova application is almost fully migrated. Now is time to handle the generated API report. Open the API report in a browser window and review the presented items. For each item in the report, you need to either implement it differently or replace it entirely. You can rerun the Migration Assistance tool, this time pointing to the new Cordova application to check again for any APIs that were not dealt with.


Step 5

To test the Cordova application, you can either preview only its web resources, run in a simulator/emulator or in a physical device.
Note: If your client-side code contains logic pertainnig to security and authentication, push notifications, adapters, and similar functionality, you might need to continue adjusting your code before being able to test it (see below). You can, however, review your application interface to make sure it is still intact.

Previewing web resources:

  • From a command-line window, navigate to the application root folder.
  • Run the command: mfpdev app preview
Note: Due to a defect in Mobile Foundation 8.0, previewing applications that contain security aspects fails. As a workaround, preview the application on an emulator or physical device.
Learn more about previewing an application's web resources.

Testing in emulator/simulator or physical device:

  • From a command-line window, navigate to the applications root folder.
  • If you're testing only UI, you can simply build and run the application: cordova run replace-with-platform-name
  • If you're also testing application logic related to Mobile Foundation, make sure to first register the application by using mfpdev app register before previewing.

Next steps

Web applications

Much like classic hybrid applications, web applications for the Mobile Web and Desktop Browsers were also managed from the MobileFirst Studio plug-in for Eclipse or MobileFirst CLI. In Mobile Foundation 8.0, development of web apps is done in the traditional fashion, with the MobileFirst web SDK available from npm, too.

Note: In previous releases, MobileFirst Server served the web application and provided a public-facing URL. In Mobile Foundation 8.0, the application is registered only in the MobileFirst Server in order to provide it with security functionality, adapters capabilities, and so on, and the serving of the web application is done by standard methods, such as serving it from dedicated web servers.

Learn more about Web application development.

Step 1

Use the Migration Assistance tool to generate an API report.
Open a command-line window and use the Migration Assistance tool in the following manner.
This might take a while to complete, depending on your Internet connection...

mfpmigrate scan --in path_to_source_directory --out path_to_destination_directory
  • Replace source_directory with the path to the common folder located in the application folder of the Studio project, for example: ../Desktop/InvokingAdapterProcedures/apps/InvokingAdapterProcedures
  • Replace destination_directory with the path to the folder where you want to save the generated API report.

After the Migration Assistance tool successfully finishes running, you can observe the following effects:

  • An API report, {app-name}-api-report.html, is generated. It contains potential actions that you need to follow to align the application implementation for use in Mobile Foundation 8.0.

Step 2

With the API report assessed, it's now time to migrate the application's structure and source.

  1. Create a new folder that will contain your application's source and resources.
  2. Copy the index.html file and the js, css, and images folders from the existing project into the created folder.
  3. From a command-line window, navigate to the migrated project's root folder and add the MobileFirst web SDK: npm install ibm-mfp-web-sdk
Before continuing to step 3, follow the instructions in the Adding the Mobile Foundation SDK to Web Applications tutorial to configure the SDK.

Step 3

The Web application is almost fully migrated. It is now time to handle the generated API report. Open the API report in a browser window and review the presented items. For each item in the report, you need to either implement it differently or replace it entirely.


Step 4

To test the migrated application:

  1. Make sure the application is registered in the MobileFirst Server.
  2. To avoid encountering Same-origin errors, set up a reverse proxy. For this purpose, you can use Node.js. For an example of a reverse proxy implementation using Node.js, see the Setting up the web development environment tutorial.

Native applications

In previous versions of the product, native applications required either the MobileFirst Studio plug-in for Eclipse or MobileFirst CLI to first create the platform-specific artifacts (WorklightAPI folder, configuration files, and so on) followed by a manual copy and paste of those artifacts into the native projects in their respective IDEs.

Starting with Mobile Foundation 8.0, support is now introduced for community-favored package managers: CocoaPods for iOS, Gradle for Android, and NuGet for Windows. With these tools being available for developers, adding the MobileFirst Native SDK is now streamlined for each platform.

Learn more about Native application development.

Step 1

Use the Migration Assistance tool to generate an API report.

Note: Currently, the Migration Assistance tool can scan only native applications that are based on MobileFirst Platform Foundation 7.1.

Open a command-line window and use the Migration Assistance tool in the following manner:

mfpmigrate scan --in path_to_source_directory --out path_to_destination_directory --type platform
  • Replace source_directory with the path to the native project, for example: ../Desktop/FormBasedAuthObjCiOS-release71
  • Replace destination_directory with the path to which you want the report to be generated.
  • Replace platform with a supported platform: ios, android, or windows.
Generate API report for native apps

After the Migration Assistance tool has run successfully, you can observe the following effects:

  • An API report, {app-name}-api-report.html, was generated and opened in your default browser. It contains potential actions that you will need to follow to align the application implementation for use in Mobile Foundation 8.0.
API report

Step 2

After you have resolved the issues in the API report, you can replace the old Native SDK with the new Native SDK.

iOS
Prerequisite: Make sure you have CocoaPods installed on your Mac computer:
  • Open a Command-line window and navigate to the root of the Xcode project.
  • Run the command: sudo gem install cocoapods, followed by pod setup. Note: These commands might take several minutes to complete.

  1. Open your project in Xcode.
  2. Delete the WorklightAPI folder from your Xcode project (move it to the trash).
  3. Modify your existing code in the following ways:
    In the Build Settings tab,
    • Remove $(SRCROOT)/WorklightAPI/include from the header search path.
    • Remove $(PROJECTDIR)/WorklightAPI/frameworks from the frameworks search path.
    • Remove any references to the static library libWorklightStaticLibProjectNative.a.
  4. In the Build Phases tab, remove the links to the following frameworks and libraries. CocoaPods will re-add these links automatically.
    • libWorklightStaticLibProjectNative.a
    • SystemConfiguration.framework
    • MobileCoreServices.framework
    • CoreData.framework
    • CoreLocation.framework
    • Security.framework
    • sqlcipher.framework
    • libstdc++.6.dylib
    • libz.dylib
  1. Make sure that Xcode is closed.
  2. Open Terminal and navigate to the root of the Xcode project.
    • Run the pod init command to create a Podfile file.
    • The Podfile file is created at the root of the Xcode project. Find it and open it in an editor of your choice.
    • Comment out or remove the existing content.
    • Add the following lines and save the changes. Remember to update the target value:
      use_frameworks!
      platform :ios, 8.0
      target "replace-with-the-name-of-the-target-in-xcode-project" do
          pod 'IBMMobileFirstPlatformFoundation'
      end
      Additional pods:
      IBMMobileFirstPlatformFoundationPush
      IBMMobileFirstPlatformFoundationJSONStore

      You can further specify additional pods in the file, in case your app needs to use the additional functionality. For example, if your app uses OpenSSL, the Podfile might look like this:
      use_frameworks!
      platform :ios, 8.0
      target "replace-with-the-name-of-the-target-in-xcode-project" do
          pod 'IBMMobileFirstPlatformFoundation'
          pod 'IBMMobileFirstPlatformFoundationOpenSSLUtils'
      end
    • Run the pod install command. This command installs the MobileFirst Native SDK, IBMMobileFirstPlatformFoundation.framework, and any other frameworks that are specified in the Podfile and their dependencies. Then, it generates the pods project and integrates the client project with the MobileFirst SDK.
  3. Open your ProjectName.xcworkspace file in Xcode by typing open ProjectName.xcworkspace from a command line. This file is in the same directory as the ProjectName.xcodeproj file. You can also double-click it from the Finder.
  4. Replace all of the existing MobileFirst imports of headers with a single entry of the following new umbrella header:
    Objective C:
    #import <IBMMobileFirstPlatformFoundation/IBMMobileFirstPlatformFoundation.h>

    Swift:
    import IBMMobileFirstPlatformFoundation
  5. In the Build Settings tab, under Other Linker Flags, add $(inherited) at the beginning of the -ObjC flag.
  6. If you are using Push Notifications or JSONStore, you need to include an independent import.

    Push Notifications
    For Objective C:
    #import <IBMMobileFirstPlatformFoundationPush/IBMMobileFirstPlatformFoundationPush.h>

    For Swift:
    import IBMMobileFirstPlatformFoundationPush

    JSONStore
    For Objective C:
    #import <IBMMobileFirstPlatformFoundationJSONStore/IBMMobileFirstPlatformFoundationJSONStore.h>

    For Swift:
    import IBMMobileFirstPlatformFoundationJSONStore

Android
Find your project's lib folder and delete the following files:
  • worklight-android.jar
  • uicandroid.jar
  • bcprov.jar
  • android-async-http.jar
  1. In Android Studio, navigate to Android → Gradle Scripts and select the build.gradle (Module: app) file.
  2. Add the following lines below apply plugin: 'com.android.application':
    repositories{
        jcenter()
    }
  3. Add the following inside android:
    packagingOptions {
        pickFirst 'META-INF/ASL2.0'
        pickFirst 'META-INF/LICENSE'
        pickFirst 'META-INF/NOTICE'
    }
  4. Add the following lines inside dependencies:
    compile group: 'com.ibm.mobile.foundation',
    name: 'ibmmobilefirstplatformfoundation',
    version: '8.0.+',
    ext: 'aar',
    transitive: true
    You can specify more artifacts in case your app needs to use the additional functionality. For example, if your app uses Push Notifications, add:
    compile group: 'com.ibm.mobile.foundation',
    name: 'ibmmobilefirstplatformfoundationpush',
    version: '8.0.+',
    ext: 'aar',
    transitive: true
    Or if you intend to use JSONStore:
    compile group: 'com.ibm.mobile.foundation',
    name: 'ibmmobilefirstplatformfoundationjsonstore',
    version: '8.0.+',
    ext: 'aar',
    transitive: true

Windows
Removing the following files from the Visual Studio project:
  • wlclient.properties
  • Newtonsoft.Json
  • SharpCompress
  • worklight-windows8
  1. Right-click the project solution and select Manage Nuget packages.
  2. In the search option, search for "IBM MobileFirst Platform", choose IBM.MobileFirstPlatform.8.0.0.0, and click Install.
  3. in Package.appxmanifest, add the Internet (client) capability.

Step 3

The Native application is almost fully migrated. Now's the time to handle the issues that were generated in the API report. Open the API report in a browser and review it. For each item in the report, you need to either implement it differently or replace it entirely.


Step 4

To test the application, run it in the specific platform's IDE.

Next steps

Supplemental reading:

Your application is now compliant with the structure that is required by MobileFoundation 8.0. You can now start looking at the adapters.



Migrating Adapters

In past releases, adapters were created, developed, and built using the MobileFirst Studio plug-in for Eclipse or the MobileFirst CLI. Starting with Mobile Foundation 8.0, adapters are now considered as standard Apache Maven projects that are created using IBM-provided archetypes for generating the Java and JavaScript adapters.

Using Maven provides to server-side developers a simple and standard way to manage and integrate required dependencies, as well as frees them to use their favorite tools during development time. Maven projects can be created from a command-line using either Maven commands, or by using the MobileFirst CLI that calls Maven commands behind-the-scenes and provides simplified commands.

Tip: You can also setup Eclipse or IntelliJ to create and develop adapters in an IDE environment.

Did you know? Mobile Foundation 8.0 introduces a DevOps-style operation mode, where once an adapter is deployed to the MobileFirst Server you can then configure various properties (for example, a username and password value for a database connection) live via the MobileFirst Operations Console, without needing to re-deploy the adapter.

Learn more about developing Java and JavaScript adapters.

The steps to migrate your adapters into Maven projects include: creating a matching new Maven project and copying into it the existing adapter's source code (with some modifications). This is then followed by building the Maven project to find any errors.

Maven adapters require Apache Maven installed on the developer workstation.

  1. Install Apache Maven.
    • Download the Apache Maven .zip.
    • Add a MVN_PATH variable, pointing to the Maven folder.
    • Mac and Linux:
      Edit your ~/.bash_profile:
      #### Apache Maven example location
      export MVN_PATH="/usr/local/bin"
    • Windows: Follow this guide.
    • Verify the installation by executing: mvn -v.
  2. The cookbook uses the MobileFirst CLI to call Maven commands to create and build the adapters.
    • If you haven't already, install NodeJS as it is a prerequisite for the tool to work.
    • From a command-line window, run the command: npm install -g mfpdev-cli (or download and install it from the Download Center in the MobileFirst Operations Console).
    • Verify the installation by executing: mfpdev -v.

Create a new adapter template that matches your own adapter type and adapter name and package name.
This eases the migration as the adpapter's metadata resembles and thus does not require extra editing.

  • From a command-line window, run the command: mfpdev adapter create
  • Select the adapter type: an HTTP or SQL JavaScript adapter, or a Java adapter.
  • Provide a GroupID.
  • If you create a Java adapter, make sure to specify the same Package Name that you have previously used (for example, "com.sample").
Create an adapter template

Before running the migration tool for actual migration, set the mode for migration. There are two supported modes.

  • migrate
    With the migrate mode one can utilize client apps migration along with server migration to migrate app and adapters to Mobile Foundation v8.0. 
  • compatibility
    When the compatibility mode is set, only server migration is allowed. The client migration will be done using the Mobile Foundation Migration Studio.

To set the migration mode, run following command.

mfpmigrate mode --type [compatibility | migrate]

Note: scan and client commands cannot be run when the mode is set to compatibility. Run the migration assistance tool with server option and specify the root directory of your older worklight project.
  1. To migrate a 7.1 worklight project into Mobile Foundation v8.0, run the migration assistance tool as follows.
    mfpmigrate server --In /Users/WorklightProject**/ --Out /Users/Migrate80Project

    SYNTAX

    mfpmigrate server [--in|-i <sourceDirectory>] [--out|-o <destinationDirectory>] [--projectName|-p <newProjectDirectory>]

    DESCRIPTION

    Performs the migration of security realms and adapters from an existing MobileFirst project.


    OPTIONS

    <sourceDirectory>: The <sourceDirectory> must be the root folder within your MobileFirst project that you want to migrate. This parameter is mandatory.

    <destinationDirectory>: The <destinationDirectory> is the directory where you expect the adapters to be migrated to.

    Migration tool scans through the adapters and realms and:

    1. Creates a template for the adapters and supported security checks.
    2. Moves the Adapter sources into the newly created maven artifact.
    3. Updates project pom with the dependencies.
    4. Creates a summary report of what is done using this tool and what other changes are to be done manually to complete the migration.
  2. For existing adapters and worklight.properties file, the tool identifies all deprecated and unsupported APIs from 7.1 adapters and does following,

    1. Replaces deprecated/unsupported APIs with appropriate v8.0 APIs.
    2. Generates v8.0 adapters for the corresponding v7.1 adapters in the specified output location.
    3. Developers can navigate to the migrated adapter directory and issue a single maven command (mvn clean install  adapter:deploy) to build and deploy the adapter to Mobile Foundation v8.0 server.
      Note: Migrated adapter pom.xml will deploy the adapter to Mobile Foundation server that is running locally. If you want to deploy it to another Mobile Foundation server instance, please update server details and credentials in pom.xml and then issue the maven command.
    4. worklight.properties file is scanned to know if any property requires explicit JNDI value inclusion on Mobile Foundation v8.0 server and outputs these entries in the report.
  3. For realms, the tool identifies all the supported and deprecated realms from the AuthenticationConfig.xml, and does the following,

    1. In the summary report, a list of realms used in user's authentication config, which are pre configured and available in v8.0 with predefined security checks is summarized. (No further action is needed for users).
    2. Unsupported realms are summarized (Support for these is not available in Mobile Foundation v8.0).
    3. For supported realms that need migration following steps are done.
      1. Identify the best fit SecurityCheck to migrate for a specific realm.
      2. Generate a SecurityCheck template with identified SecurityCheck base class , using the same name as the realm suffixed with SecurityCheck.
      3. Identify the challenge and validation methods in the realm, copy them as inline comments in the corresponding SecurityCheck method so that the user can refer to it and implement the same validation in the new SecurityCheck template generated.

        Please refer to this mapping so that it is clear as to which authentication logic implemented in the Realm methods is a correct fitment for generated SecurityCheck template.

        Adapter Authentication Realm

        Adapter Authenticator Realm is defined in AuthenticationConfig.xml. Following is a sample definition.

        
        <realm loginModule="SampleLoginModule" name="SampleRealm">
          <className>com.worklight.integration.auth.AdapterAuthenticator</className>
          <parameter name="login-function" value="SampleAdapter.onAuthTrigger"/>
          <parameter name="logout-function" value="SampleAdapter.onLogout"/>
        </realm>
        

        For the above configuration in v7.1, we can map it to a ValidationCredentialsSecurityCheck as follows.

        ValidationCredentialsSecurityCheck.createChallenge Can take the similar approach as used in SampleAdapter.onAuthTrigger to implement a challenge. However, please note that there are interface changes that needs to be taken care of while doing the migration.
        ValidationCredentialsSecurityCheck.validateCredentials Notice that there is no mapping similar to this in Realm definition above. So  mapping is not possible for this method. As a practice, we have seen that customer implements this in v7.1 in one of the resource adapter methods and calls this from the ChallengeHandler in the application upon success of cthe hallenge method.

        Similar mapping is done for all the supported realms in the v7.1 like Form Based Authenticator realm, Basic Authenticator realm, and Custom Authenticators based on their v7.1 definitions.

        Realm type in v7.1 Method definitions in the realm SecurityCheck method in
        Mobile Foundation v8.0
        CustomAuthentication createIdentity <UserAuthenticationSecurityCheck>
        createUser
        processRequest createChallenge
        CustomAuhenticator. processAuthenticationFailure
        CustomAuhenticator.changeResponse
        on success CustomLoginModule.login
        validateCredentials
        CustomLoginmodule.logout Logout
        Form Based authenticator CustomLoginModule.login <UserAuthenticationSecurityCheck>
        validateCredentials
        CustomLoginmodule.logout Logout
  4. Use Summary report to:

    1. Understand what has been through the migration assistance tool.
    2. Map unsupported to Supported APIs where straight forward migration is possible.
    3. Identify unsupported adapters/realms used in your legacy worklight project.
    4. Understand what are the other technical challenges or bottlenecks with your existing design and refer to the new development concepts below to see how they can be addressed.
HTTP JavaScript adapters
  1. Navigate in your file system to the JavaScript adapter folder, for example: ../Desktop/JavaScriptAdapters/adapters/RSSReader.
  2. Open another window and navigate to your new Maven project, for example: ../Desktop/MigratedAdapter and to the src/main/adapter-resources folder.
  3. Copy and paste your existing adapter files into this folder
  4. Edit adapter.xml: replace its contents with your existing adapter's XML content (in this example, RSSReader.xml).
  5. Edit js/{adapter-name}-impl.js: replace its contents with your existing adapter's content (in this example, RSSReader-impl.js).

SQL JavaScript adapters
  1. Navigate in your file system to the JavaScript adapter folder, for example: ../Desktop/JavaScriptAdapters/adapters/SQLAdapter.
  2. Open another window and navigate to your new Maven project, for example: ../Desktop/MigratedAdapter and into the src/main/adapter-resources folder.
  3. Edit adapter.xml: replace its contents with your existing adapter's XML content (in this example, SQLAdapter.xml).
  4. Edit js/{adapter-name}-impl.js: replace its contents with your existing adapter's content (in this example, SQLAdapter-impl.js).

This is where Maven dependencies come into play. Because Worklight/MobileFirst Studio are not used where the database connector was previously placed in the server/lib folder, you replace it with a Maven dependency.

  1. Go back to the newly created Maven project and open the pom.xml file located at the root of the directory.
  2. Add a dependency for your database type. You can search for the appropriate dependency to use in the Maven Central website.
  3. In this example, use the MySQL database. Add the following code block in the dependencies section:
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>5.1.6</version>
    </dependency>

If you have additional dependencies, the pom.xml file is where you point to them - either to a local file or to a remote dependency.

Learn more about Maven dependencies:

Here are "diagrams" as a way of looking differently at what was done so far:

Old structure of a JavaScript adapter
MyProject
├── adapters
│   ├── RSSAdapter
│   │   ├── RSSAdapter-impl.js
│   │   ├── RSSAdapter.xml
│   │   └── filtered.xsl
New structure of a JavaScript adapter
RSSAdapter
├── pom.xml
├── src
│   └── main
│       ├── adapter-resources
│       │   ├── adapter.xml
│       │   └── js
│       │        ├── RSSAdapter-impl.js
│       │        └── filtered.xml
  1. Navigate in your file system to the Java adapter folder, for example: ../Desktop/JavaAdapters/RSSAdapter.
  2. Open a separate window and navigate to your new Maven project, for example: ../Desktop/MigratedAdapter and to the src/main/adapter-resources folder.
  3. Edit {adapter-name}.xml: replace its contents with your existing adapter's XML content (in this example, RSSAdapter.xml).
  4. In the new adapter, navigate to src/main/java/com/sample/ (in this example).
  5. Replace the existing .java file with your existing adapter's .java files.

If you are using any additional libraries in the existing adapter, Maven dependencies now come into play. Because Worklight/MobileFirst Studio are not used where the libraries were previously placed either in server/lib or the Java adapter's lib folder, you replace them with Maven dependencies.

  1. Go back to the newly created Maven project and open the pom.xml file located at the root of the directory.
  2. Add a dependency for your database type. You can search for the appropriate dependency to use in the Maven Central website.
  3. This example uses a Cloudant dependency. Add the following code block in the dependencies section:
    <dependency>
    	<groupId>com.cloudant</groupId>
    	<artifactId>cloudant-client</artifactId>
    	<version>1.2.3</version>
    </dependency>

Learn more about Maven dependencies:

Here are "diagrams" as a way to look differently at what was done so far:

Old structure of a Java adapter
├── adapters
│   └── RSSAdapter
│       ├── RSSAdapter.xml
│       ├── lib
│       └── src
│           └── com
│               └── sample
│                   ├── RSSAdapterApplication.java
│                   └── RSSAdapterResource.java
New structure of a Java adapter
├── pom.xml
├── src
│   └── main
│       ├── adapter-resources
│       │   └── adapter.xml
│       └── java
│           └── com
│               └── sample
│                   ├── RSSAdapterApplication.java
│                   └── RSSAdapterResource.java
└

Building the migrated adapter

From a command-line window, navigate to the adapter's folder and run the command: mfpdev adapter build

Building adapters in command line - failures

To resolve such errors, it is recommended to import the Maven project into an IDE, such as IntelliJ, and build the project there. With an IDE at your disposal, it is easier to iterate through the build errors and resolve them one by one. Learn more about using IntelliJ and adapters.

Using IntelliJ

Testing the built adapter

To test the migrated adapter, you can eiter use the MobileFirst CLI to call your endpoints, or use Swagger from the MobileFirst Operations Console.

Learn more about testing adapters in the Testing and debugging adapters tutorial.
Supplemental reading:

With the adapters migrated to a Maven project compliant form and code, it's time look at some development concepts...



Development Topics

With applications and adapters now migrated to their new structure in Mobile Foundation 8.0, here is a discussion about some implementation concepts that have changed in the latest release.

Adapters

JavaScript adapters

Global variables and sessions

Avoid using global variables in JavaScript adapters to save data on the session - because there is no "session". This change in behavior first appeared in MobileFirst Platform Foundation 7.1. However, you can use global variables to save data for use during a single request. Keep in mind, though, that this is not a recommended practice any longer.

Learn more about creating, building, deploying, and testing adapters in the Adapters tutorials.

Security framework

The security framework in Mobile Foundation 8.0 is different from the security framework in past releases. This is why you must re-implement some of your application back-end and client logic.

It is highly preferable that you take the time to familiarize yourself with the new security framework and its authorization flow, which are now based solely on the OAuth model. Also learn about the new authorization entities such as access tokens, security checks and scopes - which replace previously known entities such as security tests, realms, and login modules.

Learn how to migrate security in the tutorial on Migrating Authentication and Security. To learn more about the security framework and authorization concepts see the Authentication and security tutorials.

Realm versus SecurityCheck

In Mobile Foundation 8.0, a security check can be seen as the combination of three concepts that exist in previous releases:
Security check = Realm + Authenticator + LoginModule

The Implementation of the security check is the implementation of both the LoginModule and the Authenticator.
The definition of a security check is similar to the definition of a realm.

The following table depicts differences between the security frameworks of past releases with the security framework in Mobile Foundation 8.0.

Previous releases Mobile Foundation 8.0
Definition Defined in the authenticationConfig.xml with a name, login module, and authenticator, for example:
<realm loginModule="AuthLoginModule" name="AuthRealm">
        <className>com.worklight.integration.auth.AdapterAuthenticator</className>
    </realm>
Define a security check in the relevant adapter.xml file with a name, and the implementing class:
<securityCheckDefinition
        name="securityCheckX"
        class="com.sample.SecurityCheckW">
    </securityCheckDefinition>
Enter/Exit methods Adapter-based authentication: would define a login/logout function, which is called by the framework on authorization requests.
<parameter name="login-function" value="AuthAdapter.onAuthRequired"/>
<parameter name="logout-function" value="AuthAdapter.onLogout"/>
Custom Authenticator + LoginModule: an init() method for startup, and processRequest() to authorise requests. The authenticator sends the login module's credentials to the login()/logout() methods.
When implementing the security check interface, the user must also implement the authorize() and introspect() methods, which are called by the framework during authorization requests. The security check handles the authentication and login/logout by itself.
Usage Encapsulated in a customSecurityTest, which can contain 1 or more realms:
<customSecurityTest name="AuthSecurityTest">
    <test isInternalUserID="true" realm="AuthRealm"/>
</customSecurityTest>
Encapsulated in a Scope element, which can contain 0 or more security checks

Security tests versus Scopes

In Mobile Foundation 8.0, a Scope is used to aggregate 0 or more security checks, which can then be used to protect local and external resources, or apps. This is similar to the CustomSecurityTest concept in previous releases.

Previous releases Mobile Foundation 8.0
Definition Defined in the authenticationConfig.xml file with a name, 1 or more security tests, and at least one security test dedicated to define the UserID.
<customSecurityTest name="AuthSecurityTest">
    <test isInternalUserID="true" realm="AuthRealm"/>
</customSecurityTest>
Defined in the MobileFirst Operations Console or via REST APIs, a scope contains 0 or more security checks.
"scopeElementMapping": {
    "ScopeElementA": "secCheck1 secCheck2"
}, 
Usage A SecurityTest can be used to protect a resource (Java adapters), a procedure (JavaScript adapters), or an application (Application descriptor).

Java adapter:
@OAuthSecurity(scope="AuthRealm")
JavaScript adapter:
<procedure name="getSecretData" securityTest="AuthSecurityTest"/>
Note: You cannot protect a resource with a realm that does not belong to a securityTest.
A scope (1 or more scope elements) can be used to protect a resource (Java adapters), a procedure (JavaScript adapters), or an application (application descriptor).

Java adapter:
@OAuthSecurity(scope="ScopeElementA ScopeElementB")
JavaScript adapter:
<procedure name="deleteUser" scope="deletePrivilege"/>
Note: You can protect a resource/application with a securityCheck that does not belong to a scopeElement mapping
UserIdentity Certain realms in a Security test define DeviceID and UserID.
<test isInternalUserID="true" realm="AuthRealm"/>
A scope is not aware of the the security checks that make up the scope.
Deployment Configured in the authenticationConfig.xml file. To change which realms make a securityTest, you must redeploy the .war file. Changed without disrupting the MobileFirst Server by using the MobileFirst Operations Console.

Notifications

In Mobile Foundation 8.0, a new push service is introduced, along with a new experience for setting up, configuring, and sending notifications. In addition, the concept of event-source push notifications has been withdrawn. Find detailed scenario-based migration paths in these user documentation topics:
Learn more about setting up notification support and sending authenticated and tag-based notifications in the Notifications tutorials.

Direct Update

The steps to deliver updates by using the Direct Update feature have changed, and some restrictions are imposed.

Learn more about how to use Direct Update in the Using Direct Update in Cordova applications tutorial.

Other

In Mobile Foundation 8.0, several other components and features have been removed. For a full list, review the Removed Components user documentation topic.

As a final treat, below is a video showcasing migration of a MobileFirst Platform Foundation 6.3 Hybrid application and adapter to a standard Cordova application and Maven project.

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