Migration¶

There are changes to Mobile Development Kit as well as migration requirements to consider when you move from one version of Mobile Development Kit to the next.

Note

If you are upgrading minor or major version, make sure you follow the upgrade notes for each version higher than your current version. e.g. If you are upgrading from 3.2 to 4.2. Please follow the upgrade notes for 4.0, 4.1 and 4.2 (if any)

General Migration Tips¶

If you have previously make a clone of any files from the /MDKClient_SDK/App_SDK/template/app folder such as:
- /App_Resources/Android/app.gradle
- /App_Resources/iOS/build.xcconfig
- Or others
You must make sure to synchronize them with their newer versions from your new target Mobile Development Kit version.

Upgrading to 24.11¶

With Mobile Development Kit V24.11, the context for various events within ObjectTable, ObjectCollection, ObjectCardCollection, KeyValueCollection, SimplePropertyCollection, DataTable and their associated controls have been updated as follows:

`ObjectCell` `onPress` and `onAccessoryButtonPress`¶

The context of the ObjectCell in ObjectCollection and ObjectTable onPress event has been changed from SectionedTableProxy to ObjectCellProxy.

`ObjectCell` `ContextMenu` Item `onSwipe`¶

The context of the Item in ContextMenu in ObjectCell onSwipe event has been changed from SectionedTableProxy to ObjectCellContextMenuItemProxy. Note that getParent will now return ObjectCellContextMenuProxy instead.

`ObjectCard onPress`¶

The context of the ObjectCard in ObjectCardCollection onPress event has been changed from SectionedTableProxy to ObjectCardProxy.

`ObjectCard ActionItem onPress`¶

The context of the ActionItem (PrimaryAction and SecondaryAction) in ObjectCard in ObjectCardCollection onPress event has been changed from SectionedTableProxy to ObjectCardActionItemProxy.

`ObjectCard OverflowButton onPress`¶

The context of the OverflowButton in ObjectCard in ObjectCardCollection onPress event has been changed from SectionedTableProxy to ObjectCardOverflowButtonProxy.

Updated Context for Proxy Classes¶

The context for each control and section within ObjectTable, ObjectCollection, and ObjectCardCollection has now been enhanced to utilize their own respective proxy classes. It is important to note that only the new Proxy classes introduced in this feature will have their context updated.

`KeyValueItem`, `SimplePropertyCell` and `DataTableRow` `onPress`¶

The context of the KeyAndValues in KeyValue, SimplePropertyCell in SimplePropertyCollection and Row in DataTable onPress event has been changed from SectionedTableProxy to KeyValueItemProxy, SimplePropertyCellProxy and DataTableRowProxy respectively.

Note

For backward compatibility, SectionedTableProxy functions are added to KeyValueItemProxy, SimplePropertyCellProxy and DataTableRowProxy at runtime. A warning log will be generated when a SectionedTableProxy function is used. These functions will be removed in an upcoming release.

If both SectionedTableProxy and ControlProxy have the redraw function, the SectionedTableProxy function takes precedence.

`DataTableCell` `onValueChange`¶

The context of the DataTableColumn > Row > DataTable onValueChange event has been changed from SectionedTableProxy to DataTableRowProxy. Note that getParent will now return DataTableRowProxy instead of DataTableProxy (previously known as DataTableSectionProxy).

Updated Context for `KeyValueItem`, `SimplePropertyCell`, and `DataTableRow`¶

The context for the KeyAndValues in KeyValue, SimplePropertyCell in SimplePropertyCollection, and Row in DataTable has been updated. Instead of using SectionedTableProxy or BindableSectionProxy, the new contexts are now KeyValueItemProxy, SimplePropertyCellProxy, and DataTableRowProxy, respectively.

Updated Context for `DataTableCell`¶

The context for DataTableColumn within a Row in DataTable has been changed. It now uses DataTableCellProxy if it's a cell, or DataTableListPickerCellProxy if it's a listPickerCell, replacing the previous SectionedTableProxy.

Upgrading to 24.7¶

Migrate Button Table's and Its `ButtonItem` Rule Context¶

In Mobile Development Kit 24.7, the context for all the properties and events of the ButtonTable and its ButtonItem has been switched from SectionedTableProxy to ButtonTableButtonProxy.

SectionedTableProxy functions are dynamically added to ButtonTableButtonProxy at runtime to maintain backward compatibility. A warning log will be generated when a SectionedTableProxy function is used. These functions will soon be deprecated.

ButtonTableButtonProxy includes a redraw function. Invoking the context redraw() function will trigger the redraw function of the SectionedTableProxy to maintain backward compatibility.

Migrate `SectionHeader`, `SectionFooter`, and `SectionHeaderItem` Rule Context¶

The context for all the properties and events of the SectionHeader, SectionFooter, and SectionHeaderItem has been switched from SectionProxy inherited class to SectionHeaderProxy, SectionFooterProxy, and SectionHeaderItemProxy, respectively. These new proxy classes share the same base class ControlProxy.

SectionProxy functions are dynamically added to ControlProxy at runtime to maintain backward compatibility. A warning log will be generated when a SectionProxy function is used. These functions will soon be deprecated.

Following functions are present in both SectionProxy and ControlProxy:

getName
getType
getPageProxy
getParent
getVisible
setVisible

Invoking the above-mentioned functions will trigger the ControlProxy functions. Both SectionProxy and ControlProxy include a redraw function. Invoking the context redraw() function will trigger the redraw function of the SectionProxy.

Color Scheme for Banner Message Action¶

The default color scheme for the Banner Message Action has been updated to red (negative) and gray (normal). To continue displaying your banner in red, set the Semantic property to Negative.

Upgrading to 6.2¶

Migrate `EncryptDatabase` to `SecureDatabaseEncryptionKey`¶

In Mobile Development Kit 6.2, EncryptDatabase flag in BrandedSettings.json is no longer supported due to security consideration as setting EncryptDatabase to false is considered unsafe because it's generating unencrypted database. It has been replaced with SecureDatabaseEncryptionKey in BrandedSettings.json.

Setting SecureDatabaseEncryptionKey to true has the exact same result as setting EncryptDatabase to true. It will be securely encrypted.

Setting SecureDatabaseEncryptionKey to false will still encrypt the offline database but with a simple key MDK, so that you can use that key to debug the content of the database if needed or use them as demo database. You should not set this flag to false in production environment. It's meant to be used for development, debugging or demo purposes only.

Forward Compatibility¶

Encrypted offline databases generated with older Mobile Development Kit version will still work in Mobile Development Kit 6.2. This means any existing apps using encrypted offline database can be upgraded to Mobile Development Kit 6.2 without issue as long as SecureDatabaseEncryptionKey is also set to true in the new version of the app.
Unencrypted offline databases generated with older Mobile Development Kit version will no longer work in Mobile Development Kit 6.2, this includes demo database. They will need to be re-generated.

Demo Mode¶

If you have enabled demo mode for your existing app and has included demo offline database files in the demo folder, then you must regenerate your demo offline database files with SecureDatabaseEncryptionKey set to false and update them in the demo folder, unencrypted demo database files will no longer work in Mobile Development Kit 6.2.

Upgrading to 6.0¶

Custom Onboarding Logo on Android¶

To give you better control of customizing the onboarding logo, you can now specify layout height and width of your logo. To do that, you must specify those value if you have previously customize the logo.

For example, if this is your customlogo.xml from:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:android="http://schemas.android.com/apk/res/android">
  <style name="OnboardingLogo">
          <item name="android:src">@drawable/custom_icon</item>
  </style>
</resources>

You need to add the android:layout_width and android:layout_height to it as well:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:android="http://schemas.android.com/apk/res/android">
  <style name="OnboardingLogo">
          <item name="android:src">@drawable/custom_icon</item>
          <item name="android:layout_width">wrap_content</item>
          <item name="android:layout_height">24dp</item>
  </style>
</resources>

Migrating Metadata¶

NativeScript 8 (used by Mobile Development Kit Client 6.0) introduces some prominent changes. To use it, you might need to update your metadata project.

For more information, see Metadata Migration.

Upgrading to 5.2¶

Onboarding Flow Upgrade on Android¶

We have improved our onboarding flow on Android. As part of this, when the client is upgraded to 5.2 version the user will be automatically redirected to onboarding login screen where they have to re-authenticate and re-generate the passcode. All the data remains intact and there will be no changes in the application behavior.

Upgrading to 5.0 or Newer¶

Deprecating OData Initialization Actions¶

Offline OData Initialize (Action.Type.OfflineOData.Initialize)
OData Service Create (Action.Type.ODataService.Create)
OData Service Open (Action.Type.ODataService.Open)

These are now unified into a single action: OData Service Initialize (Action.Type.ODataService.Initialize).

This new action can be used to initialize both offline or online OData service.

Deprecating `font-color` Styling Property¶

font-color is now deprecated and is replaced with color

Upgrading to 4.3 or Newer¶

ClientAPI.sendMobileServiceRequest function is deprecated and should not be used anymore.

It has been replaced by ClientAPI.sendRequest which has the same functionality.

Upgrading to 4.2 or Newer¶

Migrating Mobile Development Kit Modules Import¶

If you have imported Mobile Development Kit client's classes via relative path such as:

import { IControl } from './controls/IControl';

// or
import { IControl } from '../../controls/IControl';

// or
import { IView } from './controls/IView';

// and so on

These should be migrated to use mdk-core module:

import { IControl } from 'mdk-core/controls/IControl';
import { IView } from 'mdk-core/controls/IView';

Upgrading to 4.0 or Newer¶

Upgrading NativeScript Full Path Import¶

With NativeScript 6.0 or newer, you must use fully qualified module path for tns-core-modules imports.

For example:

Before version 4.0, you can write import with short path:

import * as fs from 'file-system';

In version 4.0 or newer, you must write import with fully qualified path:

import * as fs from 'tns-core-modules/file-system';

Using Built-in NativeScript Framework Modules¶

If you are importing the following NativeScript modules in your rules:

tns-core-modules/application-settings
tns-core-modules/connectivity
tns-core-modules/file-system
tns-core-modules/platform
tns-core-modules/ui/dialogs
tns-core-modules/utils/utils

These 6 modules are now part of the ClientAPI and you can access them via ClientAPI.nativescript.

You should now migrate and use them via ClientAPI.nativescript.<modulename>

e.g. ClientAPI.nativescript.appSettingsModule

For more details please see NativeScript Framework Modules

Last update: November 27, 2024