Perform a Headless Build

A headless build is a method of building and publishing an app without launching the Eclipse environment that hosts Volt MX Iris. Instead, Ant manages the build and publish process.

Conducting headless builds has a number of advantages.

A developer does not have to open Volt MX Iris to build the application. This helps to integrate the compilation and building of Volt MX Iris projects with continuous build and integration tools like Cruise Control, Maven, and Hudson.
A non-developer can handle release management.
You can specify the binaries to be copied to a specific location of your choice, which reducing the manual effort of copying the files to a specific location.
You can easily deploy an application to multiple servers.
You can build the applications for multiple platforms with a single command.
You can build applications with binaries protected mode enabled.
You will need to configure few other settings for this to work. See Application Security for more information.

Running a headless build involves the following tasks:

Prerequisites for a Headless Build
Configure the HeadlessBuild.properties File
Configure the HeadlessBuild-Global.properties File
Increase Heap Memory
Build the Application

Note: Before using conducting a headless build, ensure you have the files mentioned in Prerequisites

For headless builds, the following two files are required:

HeadlessBuild.properties
HeadlessBuild-Global.properties

Most of the effort in preparing a headless build involves configuring these files. Ant gives you the flexibility to build an app or publish it. The decision of building or publishing is configured using Modes. The modes are:

Mode 0 - The application is built, and all the binaries are generated.
Mode 1 - The application is published on Volt MX Foundry.
Mode 2 - Through this combination of modes 0 and 1, the application is built and published on the Volt MX Foundry.
Mode 3 - This mode generates a web archive file that is combined with the Volt MX Foundry archive and also generates either a .war or .ear file, depending on what you specify. You must manually deploy the app on the server, or use a separate script.
Mode 4. A combination of modes 0 and 3. The application is built and a web archive file that is combined with the Volt MX Foundry archive also is generated, along with either a .war or .ear file, depending on what you specify. You must manually deploy the app on the server, or use a separate script.

Prerequisites

Following are the prerequisites for doing headless build:

Before doing headless builds, you have to do a blank publish to Volt MX Foundry to use services in your app. Building the application is not required in this case.
Volt MX Iris is installed on your computer.
Headless builds are supported only on Volt MX Studio 4.1 plug-ins and above.
Ensure that there is no space in the file or folder names, and in the parents folder name.
If you are doing headless builds for iPhone or iPad, ensure that the Xcode in the Mac machine is available in the /Applications directory instead of the /Developers directory. To change the directory, use the command. xcode-select.
For iOS, make sure to obtain a 10-digit development team identifier from Apple. The Team ID can be found in the Membership Details of your Apple Developer account.

Note: The Team ID must not include spaces. Otherwise, the IPA generation in Volt MX Iris fails.

Configure the HeadlessBuild.properties File

The following sections explain where to find the HeadlessBuild.properties file and how to configure it. Depending on what mode you are building (either 0, 1, 2, 3, or 4), you need to set particular values in the HeadlessBuild.properties file. These are detailed in Configure the Mode.

How to Find the HeadlessBuild.properties File
Configure the Mode

How to Find the HeadlessBuild.properties File

The file HeadlessBuild.properties is stored in the project folder of your workspace. For example, if the name of your project is HelloWorld, and the name of your workspace folder is Workspace, the path in Microsoft Windows will be:

C:\Users\<username>\Workspace\HelloWorld

Example of HeadlessBuild.properties file

Following is an example of sections that are present in the HeadlessBuild.properties file and the values that can be used.

Important: If the values for any variables are left blank, then the values set through Volt MX Iris will be retained while building the application.

#Note: Please escape '\' with '\\' in all file paths#
#This file represents the Application level properties used by headless build.
project.name=app1

#mode 0-Build; 1-Publish; 2-Build & Publish; 3-Combine Web Application+VoltMX Server Archive; 4-Build & Combine Web Application+VoltMX Server Archive;
#mode-0: Application will be built for the selected build platforms
#mode-1: Based on publish.web, publish.service properties, app will be published & services will be published
#mode-2: Application will be built for selected build platforms and publish will be performed.
#mode-3: Combines web archive of app & voltmx server archive and generates combined war/ear file
#mode-4: Application will be built & Generated web archive will be combined with Volt MX server archive and final war/ear will be generated
mode=0

#build mode [release | debug]
build.mode=release

#Application details
appid=app1
#Please ensure that this is incremented while doing multiple Headless builds involving the modes 0 or 1 or 2
version=1.0.0
map_google_key=
default_locale=
#The android packagename can follow the pattern com.<orgname>.<appid>
android.packagename=com.orgname.app1

#Cloud Mode credentials (Applicable only for cloud)
cloud.username=
cloud.password=

#Provide Volt MX Foundry specific details
voltmxfoundry.url=

#Environment.Name used for publishing example using the format LocalDevEnv  
#For example, if your Volt MX Foundry Environment URL is:  
#https://mycompany.voltmxcloud.com  
#then the value is as follows: environment.name=mycompany
environment.name=  
account.id=  
mf.appname=

#Specify the platforms for which the headless build needs to run.
#Mobile Channel.
iphone=false
android=false

spa.iphone=false
spa.android=false

#Tablet Channel.
ipad=false
androidtablet=false

#Selecting Windows10 will also trigger builds for X86,X64,ARM architectures.
windows10=false

spa.ipad=false
spa.androidtablet=false
spa.windowstablet=false

#Desktop Channel.
desktop_kiosk=false
desktopweb=false

#Wearbles channel.
iphonewatch=false

#Universal Channel.
universal.iphone=false
universal.android=false

#App Extensions
iosappextension=false

#Provide iOS deployment target details in the case of iPhone or iPad.

#Ex: 8.0, 9.0, 10.0
mac.iosdeploymenttarget=
#Ex: 2.0, 3.0, 4.0
mac.watchosdeploymenttarget=
#Ex: 4.0, 5.0
mac.swiftversion=

#Provide following details to generate IPA file in the case of iPhone or iPad.
mac.ipaddress=
mac.username=
mac.password=

keychain.password=  
#Possible values for method are "app-store", "ad-hoc", "enterprise", "development"
method=  
#Examples for development.team are "G9B5P7QDV2", "PM7453S8QE"  
development.team=  
#Possible values are true/false
genipaiphone=false
genipaipad=false

#middleware server properties
middleware_server_ip=192.168.251.1
middleware_http_port=80
middleware_https_port=443
#used in cloud mode
cloud.middleware.url=

middleware_web_context=middleware
mobileweb_web_context=app1

#To build binaries with protected mode enabled.  
protectedmodeenabled.ios=true  
protectedmodeenabled.android=true  
protectedmodeenabled.web=true  
#If not specified, by default final binaries will be copied to 'binaries' folder inside project
binaries.location=

#Combine Web Application+VoltMX Server Archive. Applicable for mode = 3 or 4 #
#Full path of middleware archive (war/ear).If project has Volt MX session Manager,
#provide with-cache archive, for Http session Manager, provide without-cache archive.
combinewar.middlewarearchive=
combinewar.context=
#combinewar.war,combinewar.ear are mutually exclusive(Only one of them should be true)
combinewar.war=false
combinewar.ear=false
#Provide full path of dependant libraries,Separate with semicolon(;) if there are multiple libraries
combinewar.dependencylibraries=

#Supported context paths for Volt MX Foundry components, if customized.  
context.path.identity
context.path.workspace
context.path.accounts  
context.path.console

#Siteminder login URL if your on-premise Volt MX Foundry is protected by siteminder.  
login.siteminder.url

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.hclvoltmx.com/downloads.
Ensure that you use the corresponding version of MFCLI as that of the Iris. i.e 7.x iris, 7.x mfcli, 8.x iris, 8.x mfcli.
To encrypt the password using mfcli (using default password.encryption.key),
java -jar mfcli.jar encrypt "VoltMX@1234" Encrypted password is: en1801f1abee7b9e12426c062509e1b18epd

Configure the Mode

Depending on what mode you are building for (either 0, 1, 2, 3, or 4), you need to set values in the HeadlessBuild.properties file.

Mode 0 Properties

In Mode 0, the application is built, binaries are generated at the location specified in HeadlessBuild.properties, additionally if no location is specified they will also be copied to ///binaries, apart from the temp folder. To configure `build.properties` for mode 0, in addition to setting `mode=0`, simply set the platform you are building for to true.

For example, iphone=true

Mode 1 Properties

In mode 1, the application or services are published, the application or services are published to Volt MX Foundry, depending on the Volt MX Foundry details in HeadlessBuild.properties file. The properties are in addition to setting mode=1.

Note: In order to publish, initial build has to be done in mode 0 before you execute mode 1 and mode 2.

Mode 2 Properties

Because mode 2 is a combination of modes 0 and 1, you must set the properties described in the Mode 0 properties and Mode 1 properties, and set the property mode=2 in order to build and publish to Volt MX Foundry. For example:

#Cloud Mode credentials (Applicable only for cloud)
cloud.username=username@voltmx.com
cloud.password=Abc@123

#Provide Volt MX Foundry specific details
voltmxfoundry.url=https://mbaastest25.hcl.net:443

#Environment.Name used for publishing example using the format LocalDevEnv  
#For example, if your Volt MX Foundry Environment URL is:  
#https://mycompany.voltmxcloud.com  
#then the value is as follows: environment.name=mycompany
environment.name=

Mode 3 Properties

In mode 3, Volt MX Iris combines the web archive and the Volt MX Foundry archive which presumes the web archive is already built and generates a combined war/ear file. If the application is not built or the web archive is not available, then Volt MX Iris displays an error. To configure HeadlessBuild.properties for mode 3, in addition to setting mode=3, the following properties must be set:

Full path of middleware archive (war/ear). If project has Volt MX session Manager, provide with-cache archive, for Http session Manager, provide without-cache
archive.combinewar.middlewarearchive= <Path to middleware archive (war/ear, based on whether combinewar.ear / combinewar.war properties)>
combinewar.context= <Provide context name with which final war/ear will be generated.>
#combinewar.war and combinewar.ear are mutually exclusive(only one of them should be true)
combinewar.war=false
combinewar.ear=false
#Provide full path of dependent libraries, separated by semicolons(;) if there are multiple libraries
combinewar.dependencylibraries= <All MobileWeb dependency jars (full path) separated by semicolons(;) should be provided.>

Mode 4 Properties

Because mode 4 is a combination of modes 0 and 3, you must set the properties described in the headings Mode 0 Properties and Mode 3 Properties, and set the property mode=4.

CONFIGURE VOLT MX FOUNDRY PARAMETERS

To configure Volt MX Foundry parameters, follow these steps:

Open HeadlessBuild.properties file.
Provide user-name at cloud.username.
Provide password at cloud.password.
Provide Volt MX Foundry URL at voltmxfoundry.url.

Provide Volt MX Foundry environment name at environment.name.

Note: Providing user-name, password, and Volt MX Foundry URL are mandatory to build an application from the command line.

#Cloud Mode credentials (Applicable only for cloud)
    cloud.username=username@voltmx.com
    cloud.password=Abc@123
        
    #Provide Volt MX Foundry specific details 
    voltmxfoundry.url=https://mbaastest25.hcl.net:443  
        
    # Environment.Name used for publishing example using the format LocalDevEnv  
    # For example, if your Volt MX Foundry Environment URL is:  
    # https://mycompany.voltmxcloud.com  
    # then the value is as follows: environment.name=mycompany
    environment.name=

In order to enable services, you need to publish the app at least once from IDE.

Configure the HeadlessBuild-Global.properties File

The following sections explain where to find the HeadlessBuild-Global.properties file and how to configure it.

How to Find the build.properties File

The file HeadlessBuild-Global.properties is stored in the root folder of your workspace. For example, if the name of your workspace folder is Workspace, the path in Microsoft Windows would be something like this:

C:\Users\<username>\Workspace

Example of HeadlessBuild-Global.properties File

The following illustrates the sections that comprise the global.properties file and the values that can be used.

#The file represents the workspace level properties relevant for Headless Build
#Note: Please escape '\' with '\\' in file paths (Ex: C:\\workspace\\project)

#Specify the eclipse workspace path where the project exists.
workspace.location=

#Full Path to a jar file whose name starts with 'org.eclipse.equinox.launcher\_' in eclipse plugins folder
#Example: D:\\eclipse\\plugins\\org.eclipse.equinox.launcher_1.1.0.v20100507.jar
eclipse.equinox.path=

#Android Home-Please specify the path of Android SDK. This is needed only if Android Builds are being triggered
android.home=

Increase Heap Memory

If required, you can increase the heap memory available to your build by modifying the run file (either run.bat or run.sh). To increase the heap memory, type the following memory options in the run file.

java -Xms40m -Xmx512m -Dinput.file=%1 -Dglobal.file=%4 -cp %3 org.eclipse.core.launcher.Main -data %2 -application com.pat.tool.keditor.voltmxapplication

Generating IPA

To generate IPA, following fields need to be configured before triggering the build.

Open HeadlessBuild.properties file.
Provide Mac User-name at mac.username.
Provide Mac password at mac.password.

Provide IP address at mac.ipaddress.

#Provide following details to generate IPA file in the case of iPhone or iPad.
        mac.ipaddress=xx.xx.xx.xx
        mac.username=Username
        mac.password=p@ssword

Provide profile key chain password, export method, and Team ID.

keychain.password=p@ssword
        #Possible values for method are "app-store", "ad-hoc", "enterprise", "development"
        method="development"
        #Examples for development.team are "G9B5P7QDV2", "PM7453S8QE"
        development.team="G9B5P7QDV2"

Based on the requirement, user should set genipaiphone or genipaipad value to true.

#Possible values are true/false
        genipaiphone=true
        genipaipad=false

Value of the respective channel should be set to true.

#Mobile Channel.
        iphone=True
        android=false
        windowsphone8=false
        windowsphone81s=false

Build the application to generate IPA.

Build the Application

To build the application, follow these steps:

Navigate to your application’s workspace.
Make sure the files run.bat, build.xml, HeadlessBuild.properties, and HeadlessBuild-Global.properties are present in the workspace.
Update the HeadlessBuild-Global.properties file with details like workspace location, eclipse.equinox.path, and preference. For example.

workspace.location = c:\\Myprojects\\Releases
eclipse.equinox.path = c:\\Eclipse_6.5\\plugins\\org.eclipse.equinox.launcher_1.1.1.R36x_v20101122_1400.jar
Update the HeadlessBuild.properties file with details like project.name, application, and platforms that you are building the application for.
Open the command prompt in the workspace.
Type ant in the command prompt. You can see the status of the build on the command prompt window.

Note: If you want to write the console statements to a file for later viewing, such as for evaluating errors, use the command ant > <drive:\filename>
If the app is built for Android, you can expect the folder to have the following structure (unless otherwise defined in the binaries section of the HeadlessBuild.properties file).

New Terms (Volt MX)	Old Terms (Temenos)
Volt MX	Quantum
Iris	Visualizer
Foundry	Mobile Fabric
Foundry	Fabric
Flare	Nitro

New Namespace (Volt MX)	Old Namespace (Temenos)
voltmx	kony
com.hcl.voltmx	com.konylabs
VMXFoundry	KNYMobileFabric
Examples
voltmx.ui.Alert	kony.ui.Alert
voltmx.os.deviceInfo	kony.os.deviceInfo
com.hcl.voltmx.middleware.api	com.konylabs.middleware.api
com.hcl.voltmx.middleware.dataobject	com.konylabs.middleware.dataobject
VMXFoundry.OfflineObjects.drop	KNYMobileFabric.OfflineObjects.drop

New Terms (Volt MX)	Old Terms (Temenos)
vfcli.jar	mfcli.jar
iris	viz
Iris	Viz