Migrate projects to MobileFirst Studio v6.3.0

How to migrate the existing projects to MobileFirst Studio v6.3.0.

Migrate older MobileFirst projects to MobileFirst Studio v6.3.0

Open your existing projects (that is, projects originally created in Worklight Studio V5.0.5 through v6.2) as we would normally. This action triggers a migration process that updates them to work with v6.3.0.

When the migration process finishes, redeploy the applications and adapters.

To migrate projects created in versions of Worklight Studio older than V5.0.5, you must first migrate these projects to an intermediate level such as V5.0.5, V5.0.6, or v6.0. For example, if you have a V5.0.0.3 project:

1. Migrate the V5.0.0.3 project to Worklight Studio V5.0.5.x, using the procedures that are listed in Migrate to a newer version of IBM MobileFirst Platform Foundation of the IBM Worklight V5.0.5 user documentation.

2. Open the project (now migrated to V5.0.5) in MobileFirst Studio v6.3.0 to complete the migration process.

Access to authenticity-protected resources is denied when you upgrade existing applications to MobileFirst Studio v6.3.0. When you upgrade MobileFirst Studio, rebuild the project WAR and .wlapp, and deploy those files to the server, the existing clients that use authenticity stop working. To resolve the problem, complete the following steps:

1. Upgrade the project using the new MobileFirst Studio, as described above.

2. Increment the versions of the upgraded applications.

3. Deploy the new WAR file that was built with the new Studio.

4. Deploy the new applications to the server alongside the applications that were built with the old version of IBM MobileFirst Platform Foundation.

5. Normally, both applications work as expected. To use the new ones only, block the old ones and refer to the new ones for upgrade.

If for any reason you need to access the pre-migrated versions of the project., a compressed file backup is made of those files. The location of this file is displayed in the second step of the migration procedure.

If any of the existing target environments are removed in the newest version of MobileFirst Studio, a message notifies you, and those folders are marked as plain source folders in the file hierarchy.

If any applications in your existing projects use the obsolete database login module for user authentication, modify them to use adapter-based authentication with the SQL adapter instead.

Migrate MobileFirst Native API projects

Projects of type Worklight Native API created in earlier versions of Worklight Studio have the JAR files containing their native code rebuilt when they are migrated to MobileFirst Studio v6.3.0. As a result, after you migrate the existing Native API project, you must recopy the library and the client property files of the Native API application into the project.

• For iOS Native API projects, follow the instructions in Copy files of native API applications for iOS.

• For Android Native API projects, follow the instructions in Copy files of Native API applications for Android.

• For JavaME Native API projects, follow the instructions in Copy files of Native API applications for Java Platform, Micro Edition (Java ME).

ARC-enablement for upgraded iOS projects

The MobileFirst upgrade process does not enable ARC (Automatic Reference Counting) by default in existing iOS projects. Although ARC is enabled for the MobileFirst library, you must manually enable ARC for the upgraded project by following the steps that are described in the Apple Documentation.

iOS: changes in Xcode linker options

Before IBM MobileFirst Platform Foundation v6.2.0, the iPhone and iPad environments specified the -all_load option in the Other Linker Flags of the Build Settings to load all symbols from all libraries into the app. Starting with IBM MobileFirst Platform Foundation v6.2.0, this -all_load flag is replaced with -force_load <library> flags for each library from which all symbols are loaded.

Generally, the linker loads the symbols that are used within an app. However, in some cases, such as when Objective-C categories are used, the linker does not load all the necessary symbols, which results in unresolved symbol errors from the linker.

New v6.3.0 iOS environments and the iOS environments that are migrated from previous versions of IBM MobileFirst Platform Foundation have the -force_load flag specified for the following libraries:

• libCordova.a

• libWorklightStaticLibProject.a

• libTLFLib.a (added by the Tealeaf SDK optional feature)

• libfipshttp.a (added by the FIPS 140-2 optional feature)

You might need to add a -force_load flag for third-party libraries that you include in the project.

If we use xcodebuild to build the projects, you must specify an extra flag or property to indicate the location of the libraries for which we use -force_load. We can use either the -scheme flag (if the project was previously opened in Xcode) or the SYMROOT property (whether the project was previously opened in Xcode or not):

In the following examples, the values used for -configuration and -sdk are only indicated for illustration purposes. The values that we specify might be different.

1. If Xcode was not previously run on the generated .xcodeproj project, then specify SYMROOT (it can be any directory):
   xcodebuild -project <PathToProject>/TestProjectTestAppIphone.xcodeproj -configuration Release -sdk iphonesimulator7.0 SYMROOT=<PathToProject>/build

2. If Xcode was previously run on the generated .xcodeproj project, then we can specify the scheme:
   xcodebuild -project <PathToProject>/TestProjectTestAppIphone.xcodeproj -scheme TestProjectTestAppIphone -configuration Release -sdk iphonesimulator7.0

Targeting new iOS architectures for the existing apps

• For hybrid applications: To target armv7, armv7s and arm64, or only one architecture, you must manually change the architecture selection in the Architectures menu of the Xcode Build Settings:

  1. In Valid Architectures, select armv7 or armv7s or arm64, or all the three architectures.

  2. In Architectures, depending on the slice to create, select one, or several architectures that you chose in step 1.

     To compile or to create a slice, you must include the slice name in both Valid Architectures and Architectures (so for armv7s, you must add armv7s to both menus). Valid Architectures specifies declaratively which slice can be created. In Architectures, select only the slice to create.

• For native applications: After you replace the IBM Worklight v6.1.0 files with the v6.2.0 files in the Xcode project, we can change the selections in the Xcode Valid Architectures and Architectures menus to include any combination of armv7, armv7s, and arm64. Then compile the project for the selected architectures.

FIPS is not yet supported on 64-bit architecture even though MobileFirst library does support 64-bit architecture. Therefore, FIPS must not be enabled on 64-bit target platform when XCode Build Setting (Architecture) is also set to 64 bit.

Manually upgrading existing MobileFirst iOS hybrid applications

IBM MobileFirst Platform Foundation v6.3.0 supports existing applications created before v6.3.0. These applications can continue to work as is. However, if you want to simplify the usage of native code at the start of the application, you must manually update the application code.

To manually migrate an application to MPF v6.3.0, and use native code more are at the start of the application, follow these steps:

1. Set the main app delegate, MyAppDelegate (in appName.h), to extend WLAppDelegate instead of WLCordovaAppDelegate.

2. Implement the protocol WLInitWebFrameworkDelegate (for example, set MyAppDelegate to implement it), and implement its method wlInitWebFrameworkDidCompleteWithResult.

   The method didFinishWLNativeInit is deprecated and cannot be called. If we had custom code in this method, move it to wlInitWebFrameworkDidCompleteWithResult.

   For example, in appName.h, change

   @interface MyAppDelegate : WLCordovaAppDelegate{}
   to
   @interface MyAppDelegate : WLAppDelegate <WLInitWebFrameworkDelegate> {}
   and implement the method of the protocol:
   -(void)wlInitWebFrameworkDidCompleteWithResult:(WLWebFrameworkInitResult *)result​

   CDVMainViewController and WLCordovaAppDelegate are deprecated and are no longer necessary (if some custom applicative code interacts with these classes, it continues to work as is).

3. Call [[WL sharedInstance] initializeWebFrameworkWithDelegate:someDelegate] whenever it applies, according to the logic of the application (IBM recommends to call it as early as possible in the application lifecycle).

4. When the MobileFirst initialization process is complete, the framework notifies the delegate by calling the wlInitWebFrameworkDidCompleteWithResult method with a WLWebFrameworkInitResult object. Check the initialization result using the statusCode method of WLWebFrameworkInitResult. The success and failure scenarios are handled according to the logic of the app.

5. If the initialization finishes successfully, we can load the Cordova WebView to run the MobileFirst JavaScript framework:

   1. Call [[WL sharedInstance] mainHtmlFilePath] to get the path of the main HTML file of the app.

   2. Create the Cordova ViewController CDVViewController, and set its startPage to the HTML path.

   3. Display the Cordova WebView.

Manage the splash screen in iOS hybrid applications created before v6.2.0 that are migrated to v6.3.0

In iOS hybrid applications created before v6.2.0 that are migrated to v6.3.0, the splash screen is still managed internally by a compatibility layer in the same way it was managed in previous versions. Before v6.2.0, the showing and hiding of the splash screen was managed internally in native code by the MobileFirst Hybrid SDK. To be able to use the new splash API, migrate the application as described in Manually upgrade existing MobileFirst iOS hybrid applications.

Work with Android projects

In MPF v6.3.0, developers are encouraged to use the latest Android SDK API level supported by the MobileFirst Studio – Android 4.4 (API Level 19). Using the latest Android SDK allows the Android system to disable compatibility behaviors that slow the mobile application and to use the latest capabilities and features it includes.

When a new Android project is created, an attribute named android:targetSdkVersion is added in the androidManifest.xml file under the <uses-sdk> element, with a default value of 19. Specifies that the API Level of the application targets is Android 4.4.

The default Android SDK API level is not changed for existing projects that are opened in MobileFirst Studio v6.3.0.

(Only for projects created with versions older than IBM Worklight v6.1) The Cordova libraries are updated during the installation of Worklight Studio v6.1.0. Therefore, for Android applications, if you have any user/custom plug-in that refers to the org.apache.cordova.api package, you must replace org.apache.cordova.api with org.apache.cordova.

Change from Tealeaf V8 to Tealeaf V9

• Start with IBM Worklight Foundation v6.2.0, Tealeaf Client SDK V9 is delivered under the optional feature Tealeaf Client SDK. In previous version of IBM Worklight, the name of this optional feature was Analytics.

• WL.Analytics JavaScript API no longer delegates to Tealeaf TLT JavaScript API. WL.Analytics JavaScript API now delegates to MobileFirst internal SDK and achieves the same results as the previous behavior.

• For IBM Worklight v6.1 projects in which the Analytics optional feature is already enabled and that you upgrade to MobileFirst Studio v6.3.0: the Tealeaf artifacts are replaced, including uicandroid.jar and TLFConfigurableItems.properties on Android, all Tealeaf .h, .plist and libTLFLib.a files on iOS, and tealeaf.min.js.

  The three Tealeaf import statements are commented out in the main.m file of iPhone and iPad environments. This is necessary to avoid compile errors related to unresolved import statements, as the Tealeaf header files were removed from the Worklight SDK. The header files are available as part of the Tealeaf Client SDK optional feature. Applications that use the Tealeaf Client SDK optional feature must add the appropriate header file imports based on the Tealeaf version used.

• Applications are not automatically instrumented with Tealeaf Client SDK API calls. Make sure to instrument the application appropriately to capture the required events for Tealeaf CX server replay and analysis.

Parent topic: Upgrading to MobileFirst Studio v6.3.0