Mobile application basics

Guide
PDF
Easy

Mobile application architecture 

Application implementation for mobile devices 

There are three approaches to the implementation of mobile applications:

Native mobile application – an application designed for a specific mobile platform (iOS, Android, Windows Phone). Such an application is developed using high-level programming languages and compiled in a so-called “native OS code” that ensures the best performance. The main disadvantage of the native mobile applications is that they are not cross-platform.

Mobile web-application – a specialized website adapted to a specific mobile device. Web-applications are cross-platform but they require a stable Internet connection since they are physically located on a separate server and not on a mobile device.

Hybrid application – a mobile application wrapped in a native container. Hybrid applications are installed from the online store (just like the native ones) and have access to the same functions of a mobile device but are developed using HTML5, CSS and JavaScript. Unlike the native applications, hybrid applications can migrate between different platforms, although their performance is not as good as that of the native applications. Mobile Creatio app is a hybrid application.

The architecture of the mobile Creatio application

scr_mobile_app_architecture.png

The Creatio mobile application utilizes the Apache Cordova framework for creating hybrid applications. The Cordova framework has the following advantages:

  • Access to native device APIs for interacting with the database or peripheral devices (such as the camera or memory card).
  • Native plug-ins for using the APIs of multiple mobile platforms (iOS, Android, Windows Phone, etc.). Additionally, developing custom plug-ins enables adding extra features and extending the API. The list of supported platforms and core plug-ins is available in the Cordova documentation.

Mobile Creatio’s core provides a single interface that enables the interaction of the client parts of the mobile application. The JavaScript files that the core utilizes can be divided into basic and configuration scripts.

The basic scripts are part of the application package available in the application store. They include:

  • MVC components (page layouts, controllers, models).
  • Synchronization modules (data import and export, metadata import, file import, etc.).
  • Client classes for web-services.
  • Client classes for accessing native plug-ins.

The application downloads the configuration files during the synchronization to the Creatio application server and then saves them to the local file system. The configuration files include the manifest of Mobile Creatio, as well as section schemas and settings.

The operation scheme of Mobile Creatio 

The mobile Creatio application available in the app store is a set of modules required for synchronizing with the Creatio server used by the “desktop” (main) application. The desktop applications contain all settings and data needed for Mobile Creatio app setup. The following diagram provides an outlay of the Mobile Creatio app routine:

scr_mobile_app_working_scheme.png

After the installation, the user specifies the connection parameter for a specific Creatio server. The application then downloads metadata (application structure, system data, etc.) and regular data.

Due to this operation model, a Mobile Creatio application is compatible with all existing Creatio products. Each product and each customer website may contain an independent collection of settings for Creatio Mobile, custom business logic, and custom visual interface. All a mobile user needs to do is set up the mobile application and synchronize it with the Creatio website.

Mobile Creatio app operation modes 

A Creatio mobile application has the following operation modes available:

  • Hybrid mode. The hybrid mode is designed for accessing the data when a stable connection to the Creatio server cannot be established. It is enabled automatically. This mode enables creating new records and working with schedules. Additionally, the most recent records (10 last records) are available for reading and editing when there is no Internet connection.
  • Online. The online mode requires an Internet connection. In this mode, the user works directly with the server (the primary Creatio application). The configuration settings are auto-synced in real-time.
  • Offline. The offline mode only requires an Internet connection for the initial imports and subsequent synchronizations. In this mode, the data are stored on the mobile device. To acquire the configuration changes and update the data, run a synchronization with the Creatio application server manually.

The operation mode of a mobile application is managed by the Mobile application operation mode system setting. If you need to change the operation mode for all mobile application users, set the needed system setting value, and deselect the Save value for the current user checkbox. If you need to set different modes for different users, set the values for each user separately by selecting the Save value for the current user checkbox. These users must have permission to edit the system settings.

scr_mobile_sys_setting.png

Synchronizing mobile application with Creatio 

In different mobile app operation modes, synchronization with Creatio has different functions. In the online mode, synchronization is only required to apply the configuration changes. In the offline mode, synchronization is required both to apply the configuration changes and to synchronize the data between the mobile app and the Creatio server. The general process for synchronization performed offline:

scr_mobile_app_synch_scheme.png

First, the application performs authentication. The current active server session is destroyed upon logout. The application requests data for generating the difference package from the server. The application analyzes the received data and requests the updated and/or modified configuration schemas. After loading the schemas, the application obtains system data connected to the cached lookups (the so-called “simple lookups”), system settings, etc. After this, the data exchange with the server commences.

In the online mode, synchronization does not require the two last steps: export and import.

Note. Mobile Creatio version 7.8.6 implements another synchronization step: “Data actualization.” If this feature is enabled, this step is executed last, after data export and import. On this step, the application compares the data stored on the server to the locally stored data. If the data are different, the application will either delete the outdated data or download new data. This mechanism is designed to account for a possible access rights re-allocation or a data wipe on the server side. To enable this mechanism in the SyncOptions section manifest, set the IsAdministratedByRights property of the ModelDataImportConfig property of the specified model object to true.

Batch mode export 

By default, the mobile application sends each user-generated change sequentially. That way, each change request at least one server request. Fulfilling requests for a significant number of changes may take a considerable time.

As of version 7.9, the batch mode export has been available for faster data exchange with the server.

To enable the batch mode export, set the UseBatchExport property to true in the SyncOptions section of the manifest of the mobile application. As a result, all user-generated changes will be sent as batch requests grouped by the operation type. Available operation types: create, update and delete.

Page life cycle in mobile application 

Each page in the mobile application has several stages during the navigation process (opening, closing, unloading, returning to the page, etc.). The time passed from loading a page, to unloading it from the mobile device memory is called a page life cycle.

Page events are available on each page life cycle stage. Using page events makes it possible to extend the page functionality. The main page events include:

  • view initialization
  • finishing class initialization
  • loading page
  • loading data
  • closing page.

Understanding the page life cycle stages enables you to extend the logic of the pages.

Life cycle stages 

Attention. Only one page can be displayed on the mobile phone screen. Tablet PC can display one page in portrait orientation and two pages in landscape orientation. Due to this, the page life cycle differs for the phone and the tablet.

Opening page 

At the first opening of the page, all scripts necessary for the work of the page are loaded. After that, the controller is initialized and the view is created.

The sequence of page opening event generation:

  1. initializeView – view initialization.
  2. pageLoadComplete – event of completion the page loading.
  3. launch – initiates data loading.

Closing page 

When the page is closed, its view is deleted from the document object model (DOM) and the controller is deleted from the device memory.

The page closes in the following cases:

  • The Back button is clicked. In this case, the last page is deleted.
  • A new section is opened. In this case, all the pages that were opened earlier are deleted.

The event of page closing completion – pageUnloadComplete.

Page unload 

Page unload is performed after opening another page in the same section. The current page becomes inactive. It may remain visible on the device screen. For example, if you open a view page from the list on the tablet PC, the list page remains visible. In the same case, the list page will not be visible on the phone but it will remain in the memory. This is the difference between unloading and closing a page.

The event of page unload – pageUnloadComplete (coincides with the event of the page closing).

Return to the page 

To return to the unloaded page, click the Back button.

Returning to the page event – pageLoadComplete.

Attention. You can only use one page instance in the application. If you consistently open two identical pages and return to the first page, the launch event handler will be executed again. This should be taken into account in the development.

Mobile application background update 

The Creatio mobile application implements a synchronization mechanism for the application structure, which can work automatically in the background. Use the Update checks frequency system setting to manage the automatic synchronization process.

scr_update_setting.png

The frequency is specified as a time interval between automatic configuration updates initiated by the mobile app. The interval is specified in hours. If the setting is set to “0”, the application will always download configuration updates.

Working conditions 

The application starts the background synchronization only if the following conditions are met:

  • the mobile device uses the iOS or Android platform;
  • synchronization has not started yet;
  • the time between synchronizations (specified in the Update checks frequency system setting) has elapsed;
  • the application is launched, or the application is activated (i.e. it was previously minimized).

If changes were made during the structure update, the application will automatically restart to apply the changes when the user minimizes it or switches to another application.

Platform specifics 

  1. The background mode is implemented through a parallel running service on the Android platform. This approach ensures that the running synchronization is completed even if the user closes the application manually.

  2. On the iOS platform, the application works in the main webView, while the synchronization uses the second webView. This ensures that the user can continue working with the application while the structure synchronization is in progress.

    Unlike the Android platform, the synchronization can be interrupted when the application is closed manually or if the iOS platform closes the app itself.

In iOS applications (starting with version 7.17.2), WKWebView is used instead of UIWebView. This results in using the Cordova 6.1.1 framework and the minimum supported version of iOS 11.

WKWebView specifics:

  • Do not use absolute paths (for resources, scripts, iframe containers, etc).
  • Do not use cross-domain URLs (for resources, scripts, iframe containers and such).
  • The localStorage data are not saved when transferring to WKWebView.
  • Do not use iframe.

Learn more about changes in iOS WebView of Apache Cordova in the Cordova documentation.

To paste a link to a local file on a page, use the Terrasoft.util.toUrlScheme method to convert the corresponding path.

Pasting a link to a local file on a page
this.element.setStyle('background-image', 'url("' + Terrasoft.util.toUrlScheme(value) +'")');

Examples of links are available below.

file:///var/mobile/Containers/Data/Application/DE283C57-94BE-4116-980A-020C271D9871/Documents/BPMonline700/Downloads/afc78721-ed5f-439e-9a24-69bf56d32610/afc78721-ed5f-439e-9a24-69bf56d32610
app://localhost/_app_file_/var/mobile/Containers/Data/Application/DE283C57-94BE-4116-980A-020C271D9871/Documents/BPMonline700/Downloads/afc78721-ed5f-439e-9a24-69bf56d32610/afc78721-ed5f-439e-9a24-69bf56d32610

Specifics of using the inappbrowser plug-in:

  • All paths must be relative and should be located inside the website root folder.

    <img src="images/2.jpg">

  • Do not use cross-domain URLs (for resources, scripts, iframe containers and such).

    <img src="https://www.worldometers.info/img/worldometers-logo.gif"> <img src="file:///var/mobile/Containers/Data/Application/DE283C57-94BE-4116-980A-020C271D9871/Documents/BPMonline700/Downloads/afc78721-ed5f-439e-9a24-69bf56d32610/pic.jpg">

  • Specify the absolute path when opening the website.

    cordova.InAppBrowser.open("file:///var/mobile/Containers/Data/Application/DE..9871/Documents/BPMonline700/Downloads/afc78721-ed5f-439e-9a24-69bf56d32610/index.html", "_blank");

Opening the website using the inappbrowser plug-in is similar to WKWebView.

Resolving synchronization conflicts automatically 

During the synchronization of a mobile app working in the offline mode, the transferred data sometimes cannot be saved. This happens if:

  • A record was merged with a duplicate, and therefore does not exist.
  • A record was deleted.

The mobile application processes both cases automatically.

Merging records with duplicates 

The algorithm of resolving synchronization conflicts caused by duplicate merging:

scr_duplicates_resolving_schema.png

The application first checks the records that have been merged since the last synchronization. Namely, what records were deleted and which records replaced them. If there were no errors during the export, the import is performed. If the Foreign Key Exception or the Item Not Found Exception errors occur, the following steps are taken to resolve the conflict:

  • Creatio checks for columns with the “old” record.
  • The “old” record will be replaced with a new record which includes the merged data.

The record is sent to Creatio afterwards. When the import is finished and the information on merged duplicates is found, the “old” records are deleted locally.

Record not found 

If the server returns a “Record not found” error, the application performs the following actions:

  1. The application first checks the records that have been deleted when merged with another record.
  2. If there is no deleted record in the list, the application deletes it locally.
  3. The application deletes the record information from the synchronization log.

After this, the application considers this conflict as resolved and continues to export data.

BaseConfigurationPage class
Advanced

Page controller classes are inherited from the Terrasoft.controller.BaseConfigurationPage class that provides methods of handling the life cycle events.

Methods 

initializeView(view)

Method is called after the page view in the DOM is being created (but was not rendered). On this stage you can subscribe to the events of the view classes and perform additional actions with DOM.

pageLoadComplete(isLaunch)

Provides extension of the logic that is executed at the page load and return. The true value of the isLaunch parameter indicates that the page is being loaded for the first time.

launch()

Called only when the page is opened. The method initiates the loading of data. If you need to load additional data, use the launch() method.

pageUnloadComplete()

Provides extension of the logic that is executed at the page unload and closure.

PageNavigator class
Advanced

The Terrasoft.PageNavigator class manages the life cycle of the pages. The class enables opening and closing of the pages, updating of the irrelevant data and storing the page history.

Methods 

forward(openingPageConfig)

Method opens page according to the properties of the openingPageConfig configuration parameter object. Main properties of this object are listed in the table.

The openingPageConfig object properties
controllerName name of the controller class
viewXType view type according to xtype
type page type from the Terrasoft.core.enums.PageType enumeration
modelName name of the page model
pageSchemaName name of the page schema in configuration
isStartPage flag indicating that the page is a start page. If previously the pages have been opened, they will be closed
isStartRecord flag indicating that the view/edit page should be the first after the list. If there are other opened pages after the list, they will be closed
recordId Id of the record of the page being opened
detailConfig settings of the standard detail 
backward()

The method is closing the page.

markPreviousPagesAsDirty(operationConfig)

Method marks all previous pages as irrelevant. After returning to previous pages, the refreshDirtyData() method is called for each page. The method re-loads the data or updates the data basing on the operationConfig object.

refreshPreviousPages(operationConfig, currentPageHistoryItem)

Method re-loads data for all previous pages and updates the data basing on the operationConfig object. If the value is set for the currentPageHistoryItem parameter, the method performs the same actions for the previous pages.

refreshAllPages(operationConfig, excludedPageHistoryItems)

Method re-loads data for all pages or updates the data basing on the operationConfig object. If the excludedPageHistoryItems parameter is set, the method does not update the specified pages.

Router class
Advanced

Routing is used for managing visual components: pages, pickers, etc. The route has 3 states:

  1. Load – opens a current route.
  2. Unload – closes current route on return.
  3. Reload – restores the previous route on return.

The Terrasoft.Router class is used for routing and it’s main methods are add(), route(), back().

Methods 

add(name, config)

Adds a route.

Parameters
name unique name of the route. In case of re-adding, the latest route will override the previous one
config describes names of the functions that handle route states. Handlers of the route states are set in the handlers property
Example of method use
Terrasoft.Router.add("record", {
  handlers: {
     load: "loadPage",
     reload: "reloadPage",
     unload: "unloadLastPage"
  }
});

route(name, scope, args, config)

Starts the route.

Parameters
name name of the route
scope context of the function of the state handlers
args parameters of the functions of the state handlers
config additional route parameters
Example of method use
var mainPageController = Terrasoft.util.getMainController();
Terrasoft.Router.route("record", mainPageController, [{pageSchemaName: "MobileActivityGridPage"}]);

back()

Closes current route and restores previous.