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.
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.
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.
2
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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...
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.
Create a new folder that will contain your application's source and resources.
Copy the index.html file and the js, css, and images folders from the existing project into the created folder.
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
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:
Make sure the application is registered in the MobileFirst Server.
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.
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.
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.
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.
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.
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.
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
In the Build Settings tab, under Other Linker Flags, add $(inherited) at the beginning of the -ObjC flag.
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
Right-click the project solution and select Manage Nuget packages.
In the search option, search for "IBM MobileFirst Platform", choose IBM.MobileFirstPlatform.8.0.0.0, and click Install.
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.
Your application is now compliant with the structure that is required by MobileFoundation 8.0. You can now start looking at the adapters.
3
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.
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.
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.
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).
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.
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.
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:
Creates a template for the adapters and supported security checks.
Moves the Adapter sources into the newly created maven artifact.
Updates project pom with the dependencies.
Creates a summary report of what is done using this tool and what other changes are to be done manually to complete the migration.
For existing adapters and worklight.properties file, the tool identifies all deprecated and unsupported APIs from 7.1 adapters and does following,
Replaces deprecated/unsupported APIs with appropriate v8.0 APIs.
Generates v8.0 adapters for the corresponding v7.1 adapters in the specified output location.
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.
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.
For realms, the tool identifies all the supported and deprecated realms from the AuthenticationConfig.xml, and does the following,
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).
Unsupported realms are summarized (Support for these is not available in Mobile Foundation v8.0).
For supported realms that need migration following steps are done.
Identify the best fit SecurityCheck to migrate for a specific realm.
Generate a SecurityCheck template with identified SecurityCheck base class , using the same name as the realm suffixed with SecurityCheck.
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.
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.
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
Understand what has been through the migration assistance tool.
Map unsupported to Supported APIs where straight forward migration is possible.
Identify unsupported adapters/realms used in your legacy worklight project.
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.
Navigate in your file system to the JavaScript adapter folder, for example: ../Desktop/JavaScriptAdapters/adapters/RSSReader.
Open another window and navigate to your new Maven project, for example: ../Desktop/MigratedAdapter and to the src/main/adapter-resources folder.
Copy and paste your existing adapter files into this folder
Edit adapter.xml: replace its contents with your existing adapter's XML content (in this example, RSSReader.xml).
Edit js/{adapter-name}-impl.js: replace its contents with your existing adapter's content (in this example, RSSReader-impl.js).
SQL JavaScript adapters
Navigate in your file system to the JavaScript adapter folder, for example: ../Desktop/JavaScriptAdapters/adapters/SQLAdapter.
Open another window and navigate to your new Maven project, for example: ../Desktop/MigratedAdapter and into the src/main/adapter-resources folder.
Edit adapter.xml: replace its contents with your existing adapter's XML content (in this example, SQLAdapter.xml).
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.
Go back to the newly created Maven project and open the pom.xml file located at the root of the directory.
Add a dependency for your database type. You can search for the appropriate dependency to use in the Maven Central website.
In this example, use the MySQL database. Add the following code block in the dependencies section:
Navigate in your file system to the Java adapter folder, for example: ../Desktop/JavaAdapters/RSSAdapter.
Open a separate window and navigate to your new Maven project, for example: ../Desktop/MigratedAdapter and to the src/main/adapter-resources folder.
Edit {adapter-name}.xml: replace its contents with your existing adapter's XML content (in this example, RSSAdapter.xml).
In the new adapter, navigate to src/main/java/com/sample/ (in this example).
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.
Go back to the newly created Maven project and open the pom.xml file located at the root of the directory.
Add a dependency for your database type. You can search for the appropriate dependency to use in the Maven Central website.
This example uses a Cloudant dependency. Add the following code block in the dependencies section:
From a command-line window, navigate to the adapter's folder and run the command: mfpdev adapter build
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.
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.
With the adapters migrated to a Maven project compliant form and code, it's time look at some development concepts...
4
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.
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.
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:
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:
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.
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).
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.
<testisInternalUserID="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:
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.