MobileFirst Foundation 8.0 Migration Cookbook

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").

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.

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.

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).

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:

• Introduction to dependency mechanism (Maven.org)
• Handling dependencies (tutorial)

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

MyProject
├── adapters
│   ├── RSSAdapter
│   │   ├── RSSAdapter-impl.js
│   │   ├── RSSAdapter.xml
│   │   └── filtered.xsl

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:

• Introduction to dependency mechanism (Maven.org)
• Handling dependencies (tutorial)

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

├── adapters
│   └── RSSAdapter
│       ├── RSSAdapter.xml
│       ├── lib
│       └── src
│           └── com
│               └── sample
│                   ├── RSSAdapterApplication.java
│                   └── RSSAdapterResource.java

├── 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

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.

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