Continuous Integration for Quantum Visualizer

Introduction

CI Build allows the user to build and publish an app from the command line without any eclipse/installer dependency.

Prerequisites

Following are the prerequisites to install CI Build:

  1. Ant must be installed on the system. The required version of Ant is specified in the externaldependencies.json file that is downloaded as part of the CI tool package.
    Based on the version of the Quantum Visualizer CI Tool, the required Ant versions are as follows:
    • Ant Version 1.10.8 (or later) for Quantum Visualizer V9 SP1.
    • Ant Version 1.8.2 (or later) for Quantum Visualizer V9.
  2. Node must be installed on the system. The required version of Node is specified in the externaldependencies.json file that is downloaded as part of the CI tool package.
    Based on the version of the Quantum Visualizer CI Tool, the required Node versions are as follows:
    • Node Version 21.1.0 (or later) for Quantum Visualizer 202407.
    • Node Version 15.4.0 (or later) for Quantum Visualizer V9 SP2.
    • Node Version 13.10.1 (or later) for Quantum Visualizer V9 SP1.
    • Node Version 11.14.0 (or later) for Quantum Visualizer V9.
  3. Download and extract the zip file from the location:download.temenos-cloud.com/visualizer_enterprise/citools/<fix pack/service pack version>/visualizer-ci-tool-<fix pack/service pack version>.zip into the project location.
    For example, For V9 SP6 the URL is https://download.temenos-cloud.com/visualizer_enterprise/citools/9.6.0/visualizer-ci-tool-9.6.0.zip
  4. Copy plugindownload.js, package.json and build.js files from visualizer-ci-tool<fix pack/service pack version> folder.
  5. Open the command prompt in the project location and perform the npm install.
  6. Update plugin.dir and javaloc properties in HeadlessBuild.properties file.

CI Build for Quantum Visualizer

Starting with Quantum Visualizer V8 SP3 GA, CI build is supported in Quantum Visualizer.

NOTE: You must upgrade to V 8 SP3 to get CI build in applications created with a lower version of Quantum Visualizer than SP3

The following properties have a default value. You can configure them if required.

Property Name Property Key Default Value Property File Name
Accessibility config isA11yConfigEnabled false projectprop.xml
Android wear minimum sdk version andwearminsdkkey 7.1 (25) projectprop.xml
Android wear target sdk version andweartargetsdkkey 7.1(25) projectprop.xml
Android wear maximum sdk version andwearmaxsdkkey None projectprop.xml
Android (mobile/tablet) minimum sdk version andminsdkkey 4.0(14) projectprop.xml
Android (mobile/tablet) target sdk version andtargetsdkkey 4.0(14) projectprop.xml
Android (mobile/tablet) maximum sdk version andmaxsdkkey None projectprop.xml
iOS Deployment target version mac.iosdeploymenttarget   HeadlessBuild.properties
Apple watch Deployment target version mac.watchosdeploymenttarget   HeadlessBuild.properties
iOS swift version mac.swiftversion   HeadlessBuild.properties
Splash screen related changes     splashscreenproperties.json

In case you want to modify any of the listed properties, you can find them in the following location: <workspace name>/<application name>.

Configure HeadlessBuild.Properties

HeadlessBuild.properties file is present in the project location.

New Entries

Upgrade Quantum Visualizer project to 8.3.x or add the below new entries in HeadlessBuild.properties file:

EntriesDescription
protectedmodeenabled.iosIf the user wants to build for iOS in protected mode, change the value to true.
protectedmodeenabled.androidIf the user wants to build for android in protected mode, change the value to true.
protectedmodeenabled.webIf the user wants to build a web application in the protected mode, change the value to true.
generateobjectmodelsIf the user wants to generate the Object Models for the CI build, change the value to true.
plugin.dirPoints to the directory, where the plugins required for the build are copied.
javaloc

Java home (provide the folder location consisting bin where the Java is installed.)

Example: <Install_location>\KonyVisualizerEnterprise8.0\Java\jdk

androidHomeAndroid SDK path
For Proxy setup, the following new entries are applicable:
proxy.host
proxy.port
proxy.username
proxy.password
If you are running CI build on a system behind a proxy, provide proxy details.

NOTE: Any property which is in the projectProperties.json can be configured via the HeadlessBuild.properties file with the same key.

Existing Entries

Add the following existing entries in HeadlessBuild.properties file:

Key NameDescription
project.name Project name
modeOnly modes 0, 1 and 2 are supported
build.modeThe mode of the build. Release or Debug.
appidID of the application
#cloud mode credentials
cloud.username
cloud.password		Applicable only for cloud
#mobilefabric specific details
mobilefabric.url
environment.name
accountd.id
mf.appname
Applicable only when you are trying to publish the app.
#specify the environment you want to publish Example:qa
cloud.environment		Applicable only when you are trying to publish the app.

#The platforms for which the headless build need to run
#Mobile Channel
iphone
android

#Tablet
ipad
androidtablet

# Desktop Channel
desktopweb
# Wearables
iphonewatch
androidwearos

The value is either true or false. Enter true to build the platform else false.

Please note that you cannot build Apple watch alone. When you build for Apple watch ensure that you build for iPhone as well.

#Provide the following details for IPA generation:
mac.ipaddress
mac.username
mac.password
keychain.password
development.team.id
method
genipaiphone (to generate IPA for iPhone)
genipaipad (to generate IPA for iPad)

Enter true to generate IPA for iPhone and iPad.

For the method, possible values supported are app-store, ad-hoc, enterprise, and development.

Universal build for iOS:
universal.iPhone
universal.android

Enter true to perform universal build for iPhone.

Enter true to perform universal build for Android.

binaries.locationLocation, where the binaries are saved after the app is successfully built.

version
default_locale
android.packagename
android.versioncode
ios.bundleversion

Support has been added for the following items from V8 SP1 onwards.

keyAlias
keyPassword
keyStoreFilePath
keyStorePassword

Support has provided for the Android signing keys from V8 SP1 onwards for signing.
context.path.identity
context.path.workspace
context.path.accounts
context.path.console		Supported context paths for Quantum Fabric components, if customized.
login.siteminder.url Siteminder login URL if your on-premise Quantum Fabric is protected by siteminder.
iosappextensionApp extension of the iOS.
iosappextensionApp extension of the iOS.

IMPORTANT: There are many keys available in the HeadlessBuild.properties file. However, not all of them are applicable for the CI Build. The keys mentioned above are the only ones applicable for CI Build.

IMPORTANT: If you do not want to store your password in the headless build.properties file, you can use mfcli to encrypt your password. You can download the mfcli.jar from https://community.kony.com/downloads.

Ensure that you use the corresponding version of MFCLI as that of the Visualizer. i.e 7.x viz, 7.x mfcli, 8.x viz, 8.x mfcli.

To encrypt the password using mfcli (using default password.encryption.key),
java -jar mfcli.jar encrypt "Kony@1234"
Encrypted password is: en1801f1abee7b9e12426c062509e1b18epd

Link Native iOS System Frameworks and Exclude built-in iOS Frameworks

As part of the CI/CD process of Quantum Visualizer builds, you must add a few System Frameworks to the KonyJS targets for the VMAppWithKonyLib Xcode project in a few scenarios. If you are using third-party NFIs, while linking the third-party NFIs to the Kony JS target, you must also link the target to the dependent system frameworks of the NFI.

For example, consider that you are using the AlertView NFI that depends on the views of the UIKit framework to display alerts. After you add the AlertView NFI to the VMAppWithKonyLib Xcode project, the build might fail depending on the Xcode version due to errors such as the UIKit symbols not being found, or the UIKit internal class symbols not being found. To resolve these errors, you must add the UIKit framework to the system frameworks list.

In addition to adding the third-party dependent system frameworks, you can also mention the built-in Kony iOS frameworks that need not be packaged into the application.

To add the system frameworks or exclude built-in Kony iOS frameworks in the application, follow these steps:

  1. Navigate to the resources/common folder of the Quantum Visualizer project.
  2. Create a json file, and name it kony_frameworks.json.
  3. In the kony_frameworks.json file, do the following:
    • Add the dependent system frameworks in the systemframeworks parameter.
    • Add the built-in Kony iOS frameworks that need not be packaged into the application in the excludeFrameworks parameter.

    NOTE: You cannot use the functionality of the built-in framework after you exclude it. If you invoke the dependent functionality of an excluded framework in the app, errors may occur and the app might stop responding.

  4. Save and close the file.

Here is a sample kony_frameworks.json file:

{
    "systemframeworks" : [
        "UIKit.framework",
        "Security.framework"
    ],
    "excludeFrameworks":[
        "AR",
        "SignInWithApple"
    ]
}

Build the Application for Quantum Visualizer

Follow these steps to build the application:

  1. Open the command prompt in the project location.
  2. Run the node command node build.js in any of the following formats. These commands will download the required plugins as well as build the application.
    • node build.js --konyvizversion <version number> // This command will download the specified plugin version to'plugin.dir' location and build the app.
    • node build.js // This command will build the app with existing plugins located in 'plugin.dir'.
    • node build.js -clean // This command will re-extract the plugins from plugin.dir folder

      • NOTE: For Delta download or when the 'plugin.dir' location already has a set of plugins then, run the following command
      node build.js -c --konyvizversion <version number>

      This command will download the upgraded plugins and build the project.

  3. If the app is built successfully, the binaries are saved in the location defined in the binaries section of HeadlessBuild.properties file.

    NOTE: If the binary location is not specified in the file, the binaries are saved in the following default location.
    <projectLocation>/Binaries.

Build .js Arguments

CommandUsage

--help

-h

Help for the build.js arguments

--clean

-c

-clean

Cleans extracted bundles folder and extracts plugins again.

--konyvizversion

-kvv

To download plug-ins of specified Visualizer version.
--proxy Forwards the request through the HTTP(s) proxy server if the script is running on a restricted network. You must provide proxy server details along with credentials if required.

Usage:node build.js --clean --konyvizversion 9.0.3 --proxy http://user_name:password@proxy.server.com:proxy_port

Error Codes

The error codes are indicative of failed stage or operation. The actual error messages differ from the description mentioned below:

Example: Error code 50 describes as one of the mandatory field is missing. Actual error message will list the fields missing.

Error CodeDescription
50One or more mandatory fields are missing in HeadlessBuild.properties.
51At least one platform should be selected for the build in HeadlessBuild.properties.
52Plugin extraction failed (or) one or more mandatory plugins are missing.
53Publishing Quantum Fabric application failed.
54Quantum Fabric configuration details are missing in HeadlessBuild.properties.
Example: error message will be (cloudname, cloudpassword, envname, accountID, mfAppName) is (or) are missing.
55Project porting failed.
56There are no forms created to build the selected channels.
Example: There are no forms created for: Desktop
57JAVA_HOME not found in environment variables (or) expected Java version is not found.
58ANT_HOME not found in environment variables (or) expected ant version is not found.
59Expected node version not found.
Example: node version mismatch: required 7.10.0, found 6.10.2.
60Expected Xcode version not found.
61Expected Finalizer version not found.
62Build failed for one or more selected platforms.
64Android Home not found
65Codegen Failed
66Package Failed
67Upload of web binaries failed
68Binary Generation failed
69IPA Generation Failed

Platforms Supported

Following platforms are supported to build the CI application:

  • iPhone, iPad
  • Android mobile and tablet
  • Responsive Web publish
  • Apple watch and Android wear