kony appfactory user guide · appfactoryuserguide version1.7 5.5konyfabrictriggers 185...

Kony

AppFactory User GuideRelease V8 SP4

Document Relevance and Accuracy

This document is considered relevant to the release stated on this title page and the document version stated on the Revision History page.Remember to always view and download the latest document version relevant to the software release you are using.

© 2019 by Kony, Inc. All rights reserved 1 of 223

AppFactory User GuideVersion1.7

Copyright © 2019 Kony, Inc.

All rights reserved.

February, 2019

This document contains information proprietary to Kony, Inc., is bound by the Kony license

agreements, andmay not be used except in the context of understanding the use andmethods of

Kony, Inc., software without prior, express, written permission. Kony, Empowering Everywhere, Kony

Fabric, KonyNitro, and Kony Visualizer are trademarks of Kony, Inc. MobileFabric is a registered

trademark of Kony, Inc. Microsoft, theMicrosoft logo, Internet Explorer, Windows, andWindowsVista

are registered trademarks of Microsoft Corporation. Apple, the Apple logo, iTunes, iPhone, iPad, OS

X, Objective-C, Safari, Apple Pay, AppleWatch, and Xcode are trademarks or registered trademarks

of Apple, Inc. Google, the Google logo, Android, and the Android logo are registered trademarks of

Google, Inc. Chrome is a trademark of Google, Inc. BlackBerry, PlayBook, Research inMotion, and

RIM are registered trademarks of BlackBerry. SAP® and SAP® Business Suite® are registered

trademarks of SAP SE in Germany and in several other countries. All other terms, trademarks, or

servicemarksmentioned in this document have been capitalized and are to be considered the

property of their respective owners.



Table of Contents

1. Revision History 5

2. Kony AppFactory® CI/CD Runtime 8

2.1 Whywe need an App Factory? 8

3. Running Your First App 12

3.1 AccessManagement 12

3.2 Prerequisites 16

3.3 Creating a New AppFactory Project 21

4. Running Visualizer App 30

4.1 Builds 30

4.2 Configuration 33

4.3 Building an App 55

4.4 Running CustomHooks in Your AppFactory Project 60

4.5 Troubleshooting 85

4.6 Auto-Triggered Jobs 99

4.7 Testing an App - TestNG 116

5. Running Kony Fabric App 157

5.1 Kony Fabric Export 161

5.2 Kony Fabric Import 166

5.3 Kony Fabric Publish 171

5.4 Publishing aWeb App 174



5.5 Kony Fabric Triggers 185

6. Working with AppFactory 200

6.1 Adding New Credentials 200

6.2 Deleting Credentials 216

7. Results 220

7.1 Reviewing Results at Jenkins Console 220

7.2 Reviewing Results at Testing Console 221

7.3 Reviewing Results by Email 221

7.4 Known Issue 221

7.5 Limitations 222


1. Revision History AppFactory User GuideVersion1.7

1. Revision History

DateDocumentVersion

Description of Modifications and Release

04/29/2019 1.8 Updated the following V8 SP4 AprilFP

l Appended a new section, Including a testng.xml

File in the tests.jar File for Device Farm in Testing

an App.

02/04/2019 1.7 Updated the following for V8SP4 release.

l Appended new section Kony Fabric Triggers in

Running Kony Fabric App.

l Appended support for changing versions of

Appium in AppFactory.

l Xcode10 support in AppFactory.

10/26/2018 1.6 Appended new section Environment Specific Variables in

Kony Build Visualizer App.



DateDocumentVersion


09/24/2018 1.5 Updated document for V8 SP3 release.

Appended new topics sections

l SupportingMultiple Fabric App Versioning in Kony

Fabric App,

l External Authentication.

l APPLE_SIGNING_CERTIFICATES

l Universal Binary support, and in Configuring Build

Visualizer App, CustomHooks, and Testing an

App

l DesktopWeb support in Configuring Build

Visualizer App and Testing an App sections.

l Protected Build support in Configuring Build

Visualizer App.

l Modified Running your First App section.

l Included new limitations in Limitations section.

06/29/2018 1.4 Appended a known issue on deletion of CustomHook.

05/08/2018 1.3 Worked on few changes in Adding New Credentials.

Added new section Known Issues.

04/23/2018 1.2 Added new section Running CustomHooks.

Added Downloading Log Files section to

Troubleshooting.



DateDocumentVersion


02/07/2018 1.1 Added new sectionWorking with AppFactory.

Modified few screenshots and worked on someminor

changes.

12/18/2017 1.0 Worked on the initial draft.


2. Kony AppFactory® CI/CD Runtime AppFactory User GuideVersion1.7

2. Kony AppFactory® CI/CD Runtime

The Kony AppFactory is a combination of agile methodologies and tools that allow teams to deliver

apps at a scale. The current document focuses on the AppFactory ContinuousDelivery platform, but it

is important to understand how the AppFactory ContinuousDelivery runtime works.

2.1 Why we need an App Factory?

l Kony App Factory® allows building omni-channelmobile applicationswith a few clicks.

l The App Factory runtime automates SDLC process of your product lifecycle and reduces Time

to Market by cost effective automatic solution of product releasemanagement.

l Kony App Factory allows users to configure their backend services using Fabric and create

mobile apps using Visualizer.

Check-in the Fabric configurations and Visualizer source code into GitHub and build the

application acrossmobile, desktop, and web. Deploy the application to a specific environment

and test the application in that environment through automation testing on real devices.

The application development process consists of the following phases:

2.1.1 Access the Kony Environment

In order to access the Kony Environment, send new request to the administrator requesting to add you

as a developer to the AppFactory. The administrator enters the email of the new user in the user

management tab of Fabric and assigns the user the role of a developer within the console. Once you

are added as a developer to Fabric, you receive an email from Fabric informing the user can now

develop apps.



2.1.2 Run the Visualizer

All developers receives an email as an invitation to the Kony Fabric cloud. Click the link within the email

to access the Login screen. Once you log into the Kony Fabric, you can download Visualizer. Open the

Visualizer and create a new project or checks out an existing project from the git repository. After

incorporating the changes, check the project into GitHub.

2.1.3 Schedule a Build

In general, the developer and/or designer schedules a build. Optionally, an administrator can schedule

a build. Nightly build is an example of one such build schedule.

To perform a build, the administrator logs into AppFactory Console and clicks the link to schedule a

job. The administrator picks the channels, environment and other build parameters to schedule. The

administrator then picks the days and the time for the build. Once the selection is complete, the job is

scheduled to run.When the scheduler starts a build process, it sends the results to an email

distribution list selected by the administrator.

2.1.4 Trigger a Build

A developer performs check-in into the source control after completing a feature or making the

necessary changes to the app. At this juncture, the developer triggers to build an app. The

administrator allowsweb-hooking at source control. The administrator then logs into AppFactory

Console and creates a watcher. The watcher identifies new changes occurring at the source control.

Once the build is triggered, the watching job runs and sends the results to an email distribution list.

2.1.5 Build an App

A developer completes a feature and checks the changes into source control. The developer then logs

into AppFactory and selects the build screen to perform a build. From the build screen, the developer

chooses the environment to build the app and the designated channels (iOS and Android). The

developer can also run the test scripts against the build. The developer clicks the Run Test option. The

developer submits the build job to the AppFactory CI and/or CD runtime. The runtime compiles the

app and sends the developer an email when the build is complete.



2.1.6 Test an App

If the build is successful, the runtime executes the test scripts. Once the tests are complete, the

developer receives an email with the test results.

2.1.7 Review Results

The developer can review the email results or open testing console at AppFactory to review the test

results. The developer can compare the test results to previous runs or download the binaries used

during the testing process.

The AppFactory users can also execute the following additional steps on demand:

Scheduling Tests

In general, the developer and/or designer schedules the tests. However, an administrator can choose

the option to schedule tests. For example, test schedule is a nightly test run on an extended list of

devices. The administrator must access AppFactory console and click the link to create test job

scheduler.

The administrator picks the app binaries, test binaries, and list of devices to schedule and executes the

tests. The administrator then picks the days and times to perform the test. Once the selection is done,

the job is scheduled to run.When the scheduler starts a test process, it sends the results to an email

distribution list.

Triggering Tests

A quality engineer needs to launch Testing an App to check-in the additional tests into source control.

An administrator allowsweb-hooking at source control. Following which the administrator logs into the

AppFactory and createswatcher which tracks any new changes that happen in the source control.

Once the trigger occurs, the watching job starts to run and send the results to an email distribution list.

Publishing a Fabric App



An administrator can publish a Fabric app to KonyCloud accessing AppFactory console. The

administrator should upload Fabric app from source control to KonyCloud as an initial step. The

administrator runs import job on the KonyCloud for the upload activity. Following which the

administrator launches publish job. This deploys the already uploaded Fabric app to Kony

environment. Once publish job finishes the execution, a developer can use Fabric app endpoint with

given app key and secret.


3. Running Your First App AppFactory User GuideVersion1.7

3. Running Your First App

Before you begin to run the App for the first time on AppFactory console youmust follow these

mandatory steps to complete the configuration of your build process for your first app. Youmust

obtains the requirements such as credentials, key files, and passwords to complete the configuration.

Access Management - The first step before you proceed with running your first app is to obtain the

credentials to log into AppFactory account. For information related to accessing the AppFactory

account, refer AccessManagement.

Prerequisites - To configure an app for the first time, youmust adhere to few basic requirements. For

information on theminimum requirements to be followed, refer Prerequisites section.

Creating a New AppFactory Project - Youmust follow certain steps to create a new App Factory

project. For more information, refer Creating a New AppFactory Project.

3.1 Access Management

Kony AppFactory requires your Kony Fabric credentials to connect to AppFactory console. If you do

not have access to Kony AppFactory from your Kony Fabric console, contact your administrator to

obtain the necessary credentials.

To access the AppFactory console, follow these steps:

1. Type the URL https://manage.kony.com in the address bar and hit Enter.

The KonyCloud Sign In screen appears.


https://manage.kony.com/


2. Enter the KonyCloud account credentials provided by the administrator.

3. Click Sign In. You will be logged in to Kony Fabric Console.

4. Click Environments from the left pane.

You can view the list of environments configured for AppFactory.

5. Click Build Management to start using AppFactory on cloud account.

Based on the authentication settings, youmay need to login to use AppFactory.



3.1.1 External Authentication on AppFactory

Kony now supports external authentication on AppFactory Account. You can access the AppFactory

console using your Okta credentials. Using external authentication, you can download and access the

artefacts andMustHaves on your AppFactory Account.

Note: When external authentication is enabled for an AppFactory Account, it is enabled for all the

tenants in the account.

Follow these steps to access your AppFactory Account through third-party applications:

1. Log on to your Kony Fabric Account.

2. FromAccounts drop-down list, select App Factory Account.

If Okta is enabled, a RE-LOGIN button appears.

3. Click RE-LOGIN.

The Launch External Login window appears.



Note: If external Identity Provider user authentication is configured and you are accessing

the AppFactory account directly, the Launch External Login window appears.

4. Click Launch External Login.

TheOkta Sign In page appears.

5. Enter your Okta credentials and click Sign In.

You are logged in to your AppFactory Account with external authentication.



6. Navigate to the Environments section from the left pane and select AppFactory.

The AppFactory console appears.

3.2 Prerequisites

There are a few prerequisites to complete the configuration of your build process, for your first app.

Before starting, ensure you havemet these requirements. You need to obtain requirements such as

credentials, key files, and passwords to complete the configuration of your first app.

The following are the prerequisites to configure an App for the first time in AppFactory Console.



1. Kony Cloud account

An administrator at KonyCloud should invite a Developer and/or Designer at AppFactory

console. Once the invitation is received, a developer can log into AppFactory console. Using

these credentials the developer logs into the Jenkins console and Testing console.

2. Kony AppFactory environment

The AppFactory user needsmandatory access to the Kony AppFactory environment. The

AppFactory console and Testing console links are available under the Environments tab at

Kony Fabric (https://manage.kony.com). The KonyCloud account admin should grant access to

Administrators, Managers, Developers, Designers, and Testers in AppFactory console .

3. Kony Fabric environment

Kony Fabric environment allows a user of AppFactory to execute, build, and publishing

processes. Every user of the AppFactory needs to have access to Kony Fabric environment.

The Kony Admin provides necessary permissions to all users to access Kony Fabric

environment.

4. Visualizer project in source control

The developer needs to provide the Visualizer project before the AppFactory setup. It is

mandatory tomention the repository location at the GitHub organization. This repository should

contain atleast one project or it can be in a sub-folder. Typically, the Visualizer source is stored

as a root directory or using the project name as the document root within GitHub. The following

screenshot shows an example app calledMyProject and the contents of the project stored in

the source control.

If you check your entire project into Git under the project directory, then the root of the project is

the project name. In this case, it isMyProject.


https://manage.kony.com/


5. GITHub 2FA

To enable AppFactory to work after 2FA (two factor authentication) is enabled, youmust use a

personal access token instead of your GitHub password. Follow the steps to activate 2FA and

update your credentials in AppFactory with the personal access token:

GitHub>> Your Profile>> Security>> Enable2FA



6. Tests in source control

Visualizer project in source control requires testing. Considering this requirement, the

<root>/test/TestNG folder must contain Appium tests. The tests shall support Maven build

management system and contains pom.xml under <root>/test/TestNG. Compile the tests using

mvn compile target.

In the example structure, the test scripts for the project are located inMyProject/test/TestNG.

From the release V8SP3 , we have added support for DesktopWeb testing. DesktopWeb

testing script must exist at below pathMyProject/test/TestNG/DesktopWeb.



7. Kony Fabric project in source control

As a preliminary step, submit the Kony Fabric project to source control. Also, provide the Fabric

project repository location at the GitHub organization. The repository can contain only one

project . The repository structuremust be an unzipped Kony Fabric app. The following

screenshot shows a usual Kony Fabric project structure:

8. Apple Signing Certificates (Provide Apple Developer Account or Apple Manual Certs)

The developer must specify Apple Developer credentials to build an app. Depending on the type

of profile for the signing app, the developer needs to generate different profiles. Check

Distributionmethods in Xcode help for further reference.

AppFactory uses apple ID credentials during the build process to create a provisioning

certificate and profile for building the app.

An app developer can use their existing apple certificates and profile (instead of sharing their

apple ID credentials). To use your existing apple certificates and profile, follow these steps:


https://developer.apple.com/

http://help.apple.com/xcode/mac/9.0#/dev31de635e5


1. Generate the proper provisioning certificate and profile from the apple developer portal.

2. Download the certificates andmanually upload to AppFactory fromBuild Parameters

screen.

For detailed information on uploading the certificate to AppFactory, refer

APPLE SIGNING CERTIFICATES

9. Key store file, key store password and key password for Android

Signature data is required for APK signing. For further reference, click Sign Your App in

Android Studio help.

10. Protected Keys

If an app developer has the protected keys and want to build their app in protectedmode to

enable extra security, the AppFactory user can upload their protected keys using credential

plugin to use it as build parameters while building the app in ProtectedMode. To know more

about building an app in protectedmode using protected keys, refer Protected Build.

11. Email address

Send email notifications after every build or test set is performed. Email address needs to be

provided before the AppFactory infrastructure setup. Youmust provide it before the

infrastructure setup to change all the configurations automatically.

3.3 Creating a New AppFactory Project

Ensure the following steps to create a new AppFactory project.

To setup the app for the first time in AppFactory Console, perform the following steps:

1. Open AppFactory Console and Sign in using your Kony Account credentials. If you do not

have a Kony cloud account, contact your administrator to get access to the AppFactory and your

KonyCloud.



2. The AppFactory uses a job process for performing various tasks from creating new projects to

running tests cases. After successful login, the console displays an overview of all the

configured jobs. If it is your first time configuring a build process, you see an empty screen by

default, as there are no jobs available.

The KonyCloud account name is displayed on the top right panel. This can be the Username or

Email ID of a user. A user can log out of the console by clicking logout . User can search using

the keywords in the Search bar provided on the top panel.

The left panel constitutes of actions that users can performwith jobs. Additionally, there are

quick links the user can follow to access documentation and create a new project. Below the left

panel user can review currently scheduled jobs in Build Queue and list of nodeswhere jobs

should be executed aka Build Executor Status.

In themiddle pane, user can view the status indicator of the folder or a job, weather icon

demonstrates the stability of build, name of the folder or job, date the folder or the job was

succeeded, failed and duration it takes.

Following icons displays the status of the project:



l Sunshine with little cloud icon - Displayswhen the project is healthy, the icon indicates

the project is working properly.

l Rain with clouds icon - Displays if a project continues to fail.

l Cloud with a single drop icon: Displays if the project starts failing.

In the following example, the KitchenSinkApp andMyTime jobs are healthy with the last run

succeeding.

3. Click New App Factory Project link in the left panel. The New App Factory Project page

appears.

This page is used to create a project for building and/or testing an app.



The job is used to create CI (Continuous Integration) per project with predefined configuration

and infrastructure. To complete the configuration, perform a first time build, for the App you

want to incorporate into AppFactory.

4. Provide the following parameters:



l PROJECT_NAME should be set to the corresponding name of the Visualizer project.

Project name can be alphanumeric andmust includeminimum4 and amaximumof 17

symbols in length. Project name should start with an alphabet only.

l PROJECT_SOURCE_CODE_URL need to be set to git repository URL, based on the

location of Kony Visualizer project. The URL format is as follows https://server/<path to

repo>.git

l PROJECT_SOURCE_CODE_SERVER_TYPE is required for configuring web-hooks.

Select one of the options that match your git server. It can beGithub, Bitbucket, or AWS

CodeCommit.

l PROJECT_ROOT_FOLDER_NAME is an optional parameter. Provide a value for this

parameter only if the project is not at the root of the repository. Sub-folder depth is not

limited, but there is a limitation for Windowswith 256 characters per path to the supported

files.

l RECIPIENTS_LIST requires email(s) to which e-mail notifications on job status will be



sent. This parameter can be changed while setting the build for an App.

5. Click BUILD.

When the user clicks the BUILD button, a new project with a given PROJECT_NAME is

created. Looking at Build History user can find the status of the last triggered build. The job is

considered to be successful, if the job status indicator is a green tick. If the job status indicator is

a red circle, then consider the job did not pass.



Additional information on build execution can be found on the original job page. A list of

structured project folders and jobs is generated during the creation of a project. Information

about the last build, last stable build, last successful build, and last completed build is provided at

the end of a job page.



6. Once the job execution is complete, the project is created and can be reviewed on the landing

page of AppFactory.



In themain folder of every project, there are two sub-folders with logical structure, and grouped

by functionality. The first folder is Kony Fabric and the second one is Visualizer. User can

navigate and narrow to particular folder (e.g. Visualizer) and run the execution, to build an app.


4. Running Visualizer App AppFactory User GuideVersion1.7

4. Running Visualizer App

A developer wants to run Visualizer app throughout CI/CD process - from building an app, publishing,

and testing the app automatically. Every stage passeswith email notifications to project team. Emails

indicate the status of a stage and additional information like build or tests artifacts, test results, and

many others.

Visualizer folder is a sub-folder of project root folder. It contains three nested folders which include

build, test logic with triggers.

l Builds

l Tests

l Triggers

4.1 Builds

The build folder contains buildVisualizerApp job, which is responsible for orchestrating the build and

test logic for different channels from a single point.



buildVisualizerApp job initiates Visualizer project build stage which depends but not limited to the

parameters:

l The Kony Fabric Environment is used for building a Visualizer app and then publishing it. For

example, there can be three different Kony Fabric environments created for splitting release

stages into three phases: Development, Staging, and Production.

o A developer and/or tester use development environment to test the feature developed

into particular dev branch.

o A developer and/or tester use staging environment to test features developed in sprint

and/or release.

o An administrator uses production environment to deploy the sprint and/or release scope.

l TheOperating System (OS) can either be Apple or Android.

l Form Factor can either beMobile or a Tablet. Desktop is not yet supported.

l Channel type can be either be native or a web app

o Native build is generated by Xcode for Apple, Android SDK.

o Single Page Application (SPA) build generatesWAR file for deploying project as web

application.



l Build mode* specifies the type of binaries that are produced after a build: release or debug. For

development, debugmode is preferable. Release binaries should be signed accordingly.

The buildVisualizerApp job can be fragmented into the following logical stages:

Build stage executes the build of the project from given repository. It consists of the following stages:

l Build

l Publish artifacts to S3

l Notify on build status by e-mail

Test stage executes tests of the project from given repository. It consists of the following steps:

l Build Tests

l Notify on build tests status by e-mail

l Run Tests

l Notify on tests run status by e-mail



4.2 Configuration

To run a build flow navigate to the buildVisualizerApp job under new AppFactory project folder, select

Build with Parameters button in themenu on the left side of the screen. If it is the first time you

perform a build, you need to configure the build job. For future builds, the AppFactory stores the

settings from the previous build to make configurations of the future builds easy. The following steps

and screenshots show how to access the Build with Parameters for the job.

1. Open an app project folder and navigate to Visualizer/Builds/buildVisualizerApp.

2. You can execute Build with parameters on the job in the following ways.

l On the right of job list, you can select the icon which represents Build with Parameters

action.

l You can open drop-downmenu at the buildVisualizerApp job and choose Build with

Parameters action from the list.

l You can open the buildVisualizerApp job and execute Build with Parameters action on



the left panel of the job.

3. At the third the user can open the buildVisualizerApp job and execute Build with Parameters

action at the left panel of the job.

The buildVisualizerApp job allows you to choosemultiple channels to build, what environment

you want to deploy to and themode to build the application. Before running the build, you need

to provide all required parameters that are listed and choose required channels to build.

There are several groups of parameters that are required to run Facade job. The parameters are as

following:



1. Source control related

l PROJECT_SOURCE_CODE_BRANCH - branch required to point Git client to the

branch you push your application code. Git is supported only.

l PROJECT_SOURCE_CODE_REPOSITORY_CREDENTIALS_ID is required for

access to repository where your Visualizer project is stored.

Important: Provide Git credentials depending on git URL format. If https link is

provided, then user credentials (Username and password) are sufficient. In case of

ssh link - ssh key needs to be added.

Note: If your repository is protected with 2fa in GitHub, add the credentials using

secret text method. For steps, refer Adding New Source Code Repository

Credentials.

2. Kony Visualizer & Kony Fabric related parameters:

l BUILD_MODE allowsDebug, Release, or Release-Protectedmode. Debug build mode

adds debug information at binaries that increase their size and allows debug problematic

code.



Note: If you are building your project for automated testing, youmust build your

project in Release or Release-protectedmode.

If you build in Debugmode, the landing screen in the generated app will be Kony's

debugger screen (which your test automation scripts will most likely not be prepared

to navigate away from).

If you choose to build your Visualizer project in Releasemode, thismode will not

enable additional security and build the application in release unprotectedmode.

If you choose to build your Visualizer project in Release-protectedmode, thismode

enables additional security with encryption keys. This is the value you enter in build UI

mode at Project Settings>> Native>> iPhone/iPad/Watch or Android >> Protected

Mode in Visualizer.

For more information about the protectedmode, refer Visualizer User Guide.

Important: Set the Android KeyStore options for Release build mode. Refer to

description of Android related parameters.

l CLOUD_CREDENTIALS_ID - KonyCloud credentials

l FABRIC_APP_CONFIG - Fabric app configuration details like app name, account id or

OnPrem console, identity URLs to connect your Visualizer app to an instance of your

Fabric app published to a specific environment. You can skip this input build parameter if

you do not have any Fabric service integration.

Important: For users on AppFactory pipeline version v8.4.2.1, having Fabric hosted

on Azure, performing fabric operations like export, import etc. is not yet supported.

The support for such operations is coming as part of V9 release fromAppFactory.

l DEFAULT_LOCALE - Example: EN



3. Parameters used for enabling corresponding channel build. Click the checkbox provided across

the channel to enable the channel build.

l ANDROID_UNIVERSAL_NATIVE

l ANDROID_MOBILE_NATIVE

l ANDROID_TABLET_NATIVE

l IOS_UNIVERSAL_NATIVE

l IOS_MOBILE_NATIVE

l IOS_TABLET_NATIVE

Important: App ID must be registered prior to the build of any Apple artifacts! Please

refer to: Maintaining Identifiers, Devices, and Profiles.

l ANDROID_MOBILE_SPA

l ANDROID_TABLET_SPA

l IOS_MOBILE_SPA

l IOS_TABLET_SPA


http://developer.apple.com/


l DESKTOP_WEB

4. Android related parameters:

l ANDROID_UNIVERSAL_APP_ID - Provide the Universal app (Mobile and Tablet)

unique application ID, to identify your app on the device and in Google Play Store.

Universal app ID is the value you enter in build UI mode at Project Settings>> Native>>

Android>> Package Name.

Example: com.konyappfactory.KitchenSink

l ANDROID_MOBILE_APP_ID- Provide the unique application ID of your mobile app, to

identify your app on the device and in Google Play Store. Unique application ID is the

value you enter in a build UI mode at Project Settings >> Native >> Android >>

Package Name.




l ANDROID_TABLET_APP_ID - Provide the unique application ID of your tablet app, to

identify your app on the device and in Google Play Store. Unique application ID is the

value you enter in a build UI mode at Project Settings >> Native >> Android >>

Package Name.


l ANDROID_APP_VERSION - A version of the Android application used to enter in build

UI mode at Project Settings >> Application >> Version.

Example: 1.0.1

l ANDROID_VERSION_CODE - App internal version number is used to determine the

recent versions (higher numbers indicating themore recent versions). You enter the app

internal version number in build UI mode at Project Settings >> Native >> Android >>

Version Code.

Example: An integer value such as 1.

l GOOGLE_MAPS_KEY_ID - To us theGoogleMaps Android API, youmust provide

Google API key https://developers.google.com/maps/documentation/javascript/get-api-

key

l ANDROID_KEYSTORE_FILE - The keystore file which stores the key that is used to

sign in the Android binary. Allowed formats include .keystore, .jks.

For more information, refer official Android documentation after signing.

Note: ANDROID_KEYSTORE_FILE is an optional parameter for Android debug

mode builds.

l ANDROID_KEYSTORE_PASSWORD - The password for the keystore file selected.



https://developers.google.com/maps/documentation/javascript/get-api-key

https://developers.google.com/maps/documentation/javascript/get-api-key


Note: ANDROID_KEYSTORE_PASSWORD is an optional parameter for Android

debugmode builds.

l ANDROID_KEY_PASSWORD - The password to the key in the keystore file used to

sign in to Android library.


Note: ANDROID_KEY_PASSWORD is an optional parameter for Android debug

mode builds.

l ANDROID_KEY_ALIAS - The alias of signing key inside the keystore. For references,

click Sign Your App in Android Studio help.

Note: ANDROID_KEY_ALIAS is an optional parameter for Android debugmode

builds.



5. Apple related parameters:

l APPLE_ID - credentials at https://developer.apple.com. The account is used to generate

certificate and for signing iOS app.

l APPLE_SIGNING_CERTIFICATES - Upload an Apple Signing Certificate to

AppFactory to sign your app for iOS native channels.

Adding a new signing certificate: To add a new signing certificate, follow these steps:

1. Click Add drop-down list that displays the list of Credential Providers across

APPLE_SIGNING_CERTIFICATES.


https://developer.apple.com/


2. Select a Credential Provider from the list.

The Add Credentials window displays. Enter the following details to add a new

signing certificate:

l Domain: Displays the domain name asGlobal Credentials (Unrestricted).

l Choose Kind as Apple Signing Certificates from the drop-down list.

l Scope: Determineswhere the signing certificate is used. TheGlobal

credential is available to the object on which the credential is associated and

on all the child objects of the object. Typically, youmust use the global-

scoped credentials for jobs.

l Enter ID. It is an internal unique ID used to identify the credentials from jobs

and other configuration.

l Enter Description for the signing certificate.

l Upload the Provision Certificate to sign the IPA.

l Enter a password for the uploaded provision certificate.

l Upload aMobile Provisioning Profile.

o For single profile, upload amobile provision file.

o For multiple profiles, youmust upload a zip that containsmultiple

mobile provision profiles.



l Click Add. The new signing certificate is added in buildVisualizerApp

project.

3. Click APPLE_SIGNING_CERTIFICATES drop-down list to find the new

certificate.

4. Select the certificate.



Note: APPLE_ID or APPLE_SIGNING_CERTIFICATES only one of the two

parameters ismandatory.

Note: Currently, AppFactory does not support wild card provisioning profiles.

Important: Ensure the uploaded certificate (or) profile has not expired. If the

uploaded certificate (or) profile expires, the build fails and system throws an error.

l APPLE_DEVELOPER_TEAM_ID - Youmust provide a parameter when your Apple ID

is a part of multiple development teams. You can skip the parameter if you are enrolled in

the Apple Developer Program as an individual. You can get a value for Apple Developer

Team ID by signing in to the developer.apple.com/account and under Membership select

Team ID.

Note: If your first build of a project on AppFactory has a value for APPLE_

DEVELOPER_TEAM_ID, you need to enter the value for this parameter in each

build.

If the parameter is empty for the first build of the project, it has to remain the same for

all the upcoming builds.

l IOS_UNIVERSAL_APP_ID - A bundle ID for Universal application (Mobile and Tablet),

used to provision devices and by the operating systemwhen the app is distributed to

customers. Universal app ID is the value you enter in build UI mode at Project

Settings>> Native >> iPhone/iPad/Watch>> Bundle Identifier.


l IOS_MOBILE_APP_ID - A bundle ID for mobile application is used to provision devices

and operating systemwhen the app is distributed to customers. The value for iOS_

MOBILE_APP_ID is entered in build UI mode at Project Settings >> Native >>

iPhone/iPad/Watch >> Bundle Identifier.


https://developer.apple.com/account



l IOS_TABLET_APP_ID - A bundle ID for a tablet application is used to provision devices

and operating systemwhen the app is distributed to the customers. The value for iOS_

TABLET_APP_ID is entered in build UI mode at Project Settings >> Native >>

iPhone/iPad/Watch >> Bundle Identifier.


l IOS_APP_VERSION - A version of the iOS application used to enter in build UI mode at

Project Settings >> Application >> Version.

Example: 1.0.1

l IOS_BUNDLE_VERSION - A version of the application used to enter in build UI mode at

Project Settings>> Native>iPhone/iPad/Watch>>Bundle Version.

Example: 1.0.1

l IOS_DISTRIBUTION_TYPE- Apple developer profile is required for signing IPAs for

Apple channels build. CheckDistributionmethods in Xcode help for the references.

The purpose of distributing the build of your app to iOS Native channels is:

l Development: If you are building your app for testing and/or debugging.

l Adhoc: If you are building your app for QA and/or UAT.

l Enterprise: If you are building a release to distribute your app internally and your

company is enrolled in Apple's Developer Enterprise Program, youmust build your

app in releasemode.

l App Store: If you are building a release to distribute your app in public through an

Apple App Store. Youmust build the app in releasemode.

If you are building your app to test using App Factory's DeviceFarm integration,

you can select any of the above options.



Note: Both Development and Adhocwill allow you to install and run devices

(you physically control) registered in your Apple Developer account. Adhocwill

allow you to test using Apple's production level app services such as Push

Notifications and so on.

l APPLE_WATCH_EXTENSION: Click the checkbox to build iOS app withWatch

extension. If the checkbox is enabled, AppFactory also builds iOS binary

compatible for Apple watch.



Note: Apple watch extension build can be triggered along with iOS build only.

6. Protected Build:

PROTECTED_KEYS is used to enable additional security in application. This parameter is

mandatory for release-protectedmode build.



Adding New Keys to the application:

Kony AppFactory provides an option to build protected binaries for both Android and iOS

platform using the Kony Visualizer tool. The Kony Visualizer tool allows you to add protected

mode build support fromAppFactory.

Perform the following steps to add a new build keys for the buildVisualizerApp job.

1. Click Add drop-down list displayed across PROTECTED_KEYS.

The drop-down list displays the list of Credential Providers.


The Add Credentials window displays.



Enter the following details to add a new protected keys.


l Choose Kind as Kony Protected Mode Build Keys from the drop-down list.

l Scope: Determineswhere the build keys are used. TheGlobal credential is

available to the object on which the credential is associated and on all the child

objects of the object. Typically, youmust use the global-scoped credentials for jobs.

l Enter ID. It is an internal unique ID used to identify the credentials from jobs and

other configuration.

l Enter Description.

l Upload Public Key, Private Key, and Fin Keys files.

Note: Fin Keysmust be provided as a zip file. It should not have any sub-folder

within the zip.



l Click Add. The new Kony Protected buildVisualizerAppMode Build Keys is

added in project.

3. Click PROTECTED_KEYS drop-down list.

You can find the new build keys in the drop-down list.

4. Select the new build keys.

Note: From release version V8 SP3 and above. uploading Fin Keys is optional.

7. DesktopWeb and SPA related parameters

l PUBLISH_FABRIC_APP enabled if user want to publish the App to Kony Fabric

Cloud/OnPrem.

Note: If you are building both DesktopWeb and SPA channels and the checkbox is

selected, a combined archive is generated and published to the selected Kony Fabric

environment.



l WEB_APP_VERSION: App version of theWeb (DesktopWeb and SPA) application.

The app version value is entered in the Build UI mode at Project Settings>>

Application>> Version.

Example: Version 1.0.1

l FORCE_WEB_APP_BUILD_COMPATABILITY_MODE: Enable the checkbox to build

the web app package using the older (war) extension. It is the value that you generally

enter in the Build UI mode at Project Settings>> Application>> Force Web App Build

Compatibility Mode.

Important: .war extension is not supported with multi-tenant environment in Kony

Fabric.

Note: Newer extension (zip) is only supported with V8 service pack 2 on KonyCloud.

If your app is using a lower set of plugins, keep the checkbox enabled.

8. Custom Hooks - The following parameter is applicable only for CustomHooks.



RUN_CUSTOM_HOOKS click the checkbox for CustomHooks execution.

Note: You can uncheck the check box to skip AppFactory CustomHooks execution.

9. Testing - Choose one of the Test Frameworks in which tests have been written for testing the

application.

10. Native Testing related Parameters - The following parameters are applicable only if you want

to fire automated tests on native app generated by this build.

l AVAILABLE_TEST_POOLS enables tests on selected device pool.

l RUN_IN_CUSTOM_TEST_ENVIRONMENT click the checkbox to execute tests in

Device Farm onCustomTest Environment. For more information on refer CustomTest

Environment Run.

Note: If the checkbox is not selected, the tests are executed in Standardmode.



l APPIUM_VERSION Enter the appium version to run your tests. Newer version such as

1.9.0 will be installed on the environment as a part of AWS run.

For more information on supported versions of Appium on AWS DeviceFarm, refer

CustomTest Environment Run.

For information on artifacts available in the notificationmail for AWS Custom

Environment Run, refer Building an App in AWS CustomEnvironment.

Note: The parameter is valid only if RUN_IN_CUSTOM_TEST_ENVIRONMENT is

selected.

l TESTNG_FILES Path of the TestNG file(s) in your testing JAR. Testng.xml located in the

root of the JAR is selected by default. You can specify the path of your TestNG file.

To specifymultiple TestNG file paths, use comma separated path values such as

kony/Testng.xml, kony/appfactory/Testng.xml, testng.xml has three

TestNG files at different locations to be rendered.

Note: If TestNG file specified in the parameter is not found in the source, the tests will

run independently similar to Standard Test Environment.

11. Web Testing related Parameters: The following parameters are applicable only if you want to

fire automated tests on web app generated by this build.

l RUN_DESKTOPWEB_TESTS_ARGUMENTS allows you to pass arguments in Maven

command to the DesktopWeb tests.



Example: If you pass -Dsurefire.suiteXmlFiles=resources/Testng.xml,

the argument will trigger the tests present in resources/Testng.xml file. If you do

not pass TestNG file, Testng.xml is selected as a default file.

l AVAILABLE_BROWSERS allows you to select the browser to run the DesktopWeb

tests.

Note: Currently, AppFactory supports onlyGoogle Chrome version 68.0.3419.0 for

DesktopWeb testing.

l RUN_DESKTOPWEB_TESTS - select the checkbox to execute DesktopWeb tests.

Important: Prerequisites for testing:

Appium testsmust be placed under <project folder>/test/testNG

folder.

Selenium tests (DesktopWeb tests) must be placed under <projectfolder>/test/testNG/DesktopWeb.

12. Notifications - The following parameter is used to configure settings specific to notifications.

RECIPIENTS_LIST is comma-separated list of recipients e-mails.

13. Click Build to build the Visualizer app.



4.3 Building an App

1. Once all parameters are specified in the buildVisualizerApp job, trigger the BUILD button.

Build proceedswith the following steps:

l Check out project fromGit repository.

l Build of Visualizer project.

l Signing artifacts - this step is required for Apple IPA/property list generation and Android

APK

l Publish artifacts to S3 bucket

l Notify on build status by e-mail

Upon build completion, notification is sent by e-mail. E-mails contains generic information about

build and list of artifacts with corresponding links to S3 bucket.



2. Check e-mail on success of all channel.

For AWS Custom Environment Run the following artifacts are available in the notificationmail.



l Logcat.logcat

l TCP dump log.txt

l Test spec output.txt

l Video.mp4

Customer Artifacts.zip will have the test output contents and Test spec output.txt will have the

AWS console output of the tests run on CustomEnvironment.



3. Check e-mail on unsuccessful build of any channel.

4. Check e-mail on unsuccessful single channel build



4.4 Running CustomHooks in Your AppFactory Project

CustomHooks are custom pipelines that you can set up to run as part of the AppFactory build flow.

These hooks can only run at certain stages of the build flow. You can define a custom logic as an ANT

script or aMAVEN script.

You can access the CustomHook features from the CustomHooks Management Console. You can

access this console from a folder called CustomHooks in the Visualizer sub folder of your project.


https://ant.apache.org/

https://maven.apache.org/


TheCustomHooks Management Console opens up when you click on the CustomHooks folder.



Note: Tomake use of the CustomHooks feature, you need to create a new project from the

AppFactory Console. For more information, refer to the Creating a New AppFactory Project

section.

The existing projects will still work without any impact, you cannot enable the CustomHooks

feature for these projects.

4.4.1 CustomHooks Management Console

TheCustomHooks Management Console is a dashboard that you can use tomanage your

CustomHooks. The console showsHook Points that specify the stages at which the parent job,

buildVisualizerApp, runs the given hooks.

There are three hook points, or stages, in the build flow.

l Pre-Build - It runs the CustomHooks after the CI process initiates and before the Build process

starts.

l Post-Build - It runs the CustomHooks after the Build process ends and before the Test process

starts.

l Post-Test - It runs the CustomHooks after the Test process ends and before the Deployment

process starts.



4.4.2 Creating CustomHooks

A CustomHook is a zip archive file that contains a logic written in java code and a build script to

compile or run this java code. You can write your own logic to apply on the workspace of your app's

code. The build script should be written in a build.xml file for ANT scripts, or pom.xml file for MAVEN

scripts.

AppFactory extracts the zip file at the specified stage and calls the ANT or MAVEN script based on the

script type selected in the Build Action parameter.

CustomHook Example

This section talks about creating a simple Hello World CustomHook using Ant or Maven scripts.

You need to implement your custom logic in a java code. Let's take an example of a Hello World java

program.

package project;

public class HelloWorld

{

public static void main(String[] args)

{

System.out.println("Hello World");

}

}

Note: Ensure that your package namematches the folder structure of your CustomHook.

For example, if your folder structure is src/prog/HelloWorld.java, then your package name should

be prog.

After you create you java file, you need to create an Ant script or aMaven script. You can findmore

information about these scripts from the following links.



l Apache Ant

l ApacheMaven

l Example for an Ant script

l Example for aMaven Script

Important:l You should create the hook script in such a way that you include specific goals for it. These

goals can be specific jobs such as compiling the java code or building a jar file. You can

call these jobs by passing them asScript Arguments in the CustomHookParameters.

l A CustomHook that runs as part of a Pre-Build or Post-Build stage has direct access to the

project files. You can add CustomHooks that have goals specific to your project build as

well. For example, a CustomHook that configures Xcode settings for iOS, or a CustomHook

that configures Android permissions, and so on.

Let's take an example of an Ant script for the given Hello World java program. This script should be in

a build.xml file at the root location of your CustomHook zip archive.

<project>

<target name="clean">

<delete dir="build"/>

</target>

<target name="compile">

<mkdir dir="build/classes"/>

<javac srcdir="src" destdir="build/classes"/>

</target>

<target name="jar">

<mkdir dir="build/jar"/>

<jar destfile="build/jar/HelloWorld.jar"


https://ant.apache.org/

https://maven.apache.org/

http://ant.apache.org/manual/tutorial-HelloWorldWithAnt.html#four-steps

http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html#The_POM


basedir="build/classes">

<manifest>

<attribute name="Main-Class"

value="project.HelloWorld"/>

</manifest>

</jar>

</target>

<target name="run">

<java jar="build/jar/HelloWorld.jar" fork="true"/>

</target>

</project>

For information on Environment Specific Variables in Kony Visualizer App, click here.

After you create the java file and the ant script, your folder structure should look similar to the structure

in the given screenshots.

You need to then compress the hook folder to a zip archive to upload it as a CustomHook to your

AppFactory Project.

When you run this CustomHook as part of any job, you can see [ java ] Hello World in the console

output of the job.



4.4.2.1 CustomHook Parameters

Go to the CustomHooks Management Console on your AppFactory project. Click the Upload button

on the stage at which you want to run your CustomHook.

A new page opens up to create a CustomHook. This page shows the build parameters required to

create the CustomHook.

The page contains the following fields:

l HOOK_NAME - This text field specifies the name that you want to give to your CustomHook.

The CustomHooksManagement Console displays this name in the respective Hook Point.

l HOOK_CHANNEL - This drop-downmenu specifies the channel on which you want to run

your CustomHook. This includes both Native and SPA channels. The HookChannel parameter

is set to ALL by default.



The IPA_STAGE for iOS platforms is the stage that generates the KAR file for iOS builds. You

can include iOS specific hooks, such as hooks for Xcode settings, at this stage.

Note: Currently, AppFactory supports only single-selection of HookChannels. If you want

to run the same hook for multiple channels, you will need to createmultiple CustomHooks

with the sameHook Archive.

l BUILD_ACTION - This drop downmenu specifies the type of script you want to run for the

CustomHook. You can choose to run either an ANT script or aMAVEN script. The Build Action

parameter is set to Execute Ant by default.

l HOOK_ARCHIVE_FILE - This button opens a new window that you can use to navigate to and

open a CustomHook zip file.



The zip file should contain an XML file at the root location, based on the BUILD_ACTION

parameter.

o ANT - The zip file should contain a build.xml file at the root location.

o MAVEN - The zip file should contain a pom.xml file at the root location.

l SCRIPT_ARGUMENTS - This text field specifies the arguments you want to pass to the

CustomHookScript. These arguments are specific the targets or goals for the script. If you

leave the Script Arguments empty, the CustomHook script will only execute the default goals.

Note: The arguments should be separated using space. They should also be in the order

you want to execute them in, from Left to Right.

l PROPAGATE_BUILD_STATUS - This check-box specifies whether the parent job should fail

if the CustomHook execution fails. This check-box is enabled by default.



After filling in the required parameters, you can Build the CustomHook.

4.4.3 Configuring CustomHooks

After you build the CustomHooks, you can configure them from the CustomHooks Management

Console. You can add upto five CustomHooks in every stage.

AnyCustomHook that you create is set as disabled, by default. You need tomanually enable the

hooks from the CustomHooksManagement Console for them to execute during the build process.

You can perform the following tasks from the CustomHooksManagement Console.

l You can enable a hook by clicking on the tick icon.

l You can delete a disabled hook by clicking on the bin icon.

o If you delete a CustomHook from the console, it will be deleted permanently.

o You can only delete disabled hooks. If you want to delete an enabled hook, you need to

disable it first.



Once you enable a hook, the name shows up in blue and the icons change fromEnable and

Delete to Edit and Disable.

The Edit and Disable buttonswill only show upwhen you hover your cursor over a

CustomHook.

l You can disable an enabled CustomHook by clicking on the Disable icon.

l You can edit a CustomHook by clicking on the Edit icon.

l You can drag and drop the enabled hooks to change their order of execution.



4.4.3.1 Editing CustomHook Parameters

Go to the CustomHooks Management Console on your AppFactory project. Click on the edit button

on the CustomHook that you want to update.

A new page opens up to update the CustomHook. This page shows the build parameters that you

configured while creating the CustomHook.



You can change any parameter while updating the CustomHook, including the job zip file.

Important:l Changing the name of the CustomHook on the _updateCustomHook page will rename the

Hook on the CustomHooksManagement Console.

l Uploading a new Hook Archive zip file is optional.

o If you upload a new zip file, then the hook job will use it.

o If you don't upload a new zip file, then the hook job will use the already existing zip file.

4.4.4 Enabling CustomHooks in Visualizer Jobs

You can choose whether to run CustomHooks as part of the buildVisualizerApp job from its build

parameters.



If you disable RUN_CUSTOM_HOOKS in the build parameters, the buildVisualizerApp job will not

run anyCustomHooks. If you want to choose which CustomHooks to run, you can do so from the

CustomHooksManagement Console.

4.4.5 CustomHook Stages in Stage View

When you enable a CustomHook in a parent job, the CustomHook stages also show up in the parent

job's Stage View.

If you enabled PROPAGATE_BUILD_STATUS in the Hook Parameters and your CustomHook fails

to execute, then the you will see a failuremessage in the parent job's stage view.

4.4.6 CustomHooks Console Output

The execution stages for CustomHooks are logged in the Console Output. These logs are available

both in the job's console output and the CustomHook job's console output.

Parent Job Console Output:



CustomHook Job Console Output:

You can access the CustomHookConsole Output from the CustomHook build pipeline page.



The console output has logs relevant to the CustomHook execution. It also contains logs for the jobs

performed as part of the CustomHook arguments.



4.4.7 Environment Variables

TheCustomHooks feature in Kony AppFactory allows you to add a custom pipeline at specific points

to an existing pipeline by using custom code/programs. Using the CustomHooks feature, you can

extend and customize the build process, while maintaining the core functionality of the AppFactory

build process. You can write custom logic and use it to override an existing operation or perform a new

operation. For more information on CustomHooks, refer Configuring CustomHooks.

Kony AppFactory exposes environment-specific variables that you can use to customize the

environment. The platform-specific channel job parameters are available during the execution of a

CustomHook.

For example, you can access Android specific environment variables that will be exposed when you

run Android specific jobs on CustomHooks.

CustomHooks also expose Source code specific variables, which point to the static location of

Binaries, and other source code files.

For example, you can use the PROJECT_XCODEPROJECT variable to get the location of the project,

and then, update the XCode Project Settings or modify any file in the project using ANT or MAVEN

files.

4.4.7.1 Platform Specific Environment Variables

Following are the environment variables for different platforms in AppFactory. These environment

variables are exposed during the build execution of CustomHooks in the channel jobs.

Parameter Platform

ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES_

ENABLEMENT

Android

ANDROID_APP_VERSION Android

ANDROID_KEYSTORE_FILE Android

ANDROID_KEYSTORE_PASSWORD Android



Parameter Platform

ANDROID_KEY_ALIAS Android

ANDROID_KEY_PASSWORD Android

ANDROID_MOBILE_APP_ID Android

ANDROID_TABLET_APP_ID Android

ANDROID_UNIVERSAL_APP_ID Android

ANDROID_VERSION_CODE Android

DEFAULT_LOCALE Android

FABRIC_APP_CONFIG Android

FORM_FACTOR Android

GOOGLE_MAPS_KEY_ID Android

RUN_CUSTOM_HOOKS Android

RECIPIENTS_LIST Android

PROJECT_BUILDNUMBER Android

PROJECT_NAME Android

BUILD_MODE Android

CLOUD _CREDENTIALS Android

PROTECTED_KEYS Android



Parameter Platform

PUBLISH_FABRIC_APP Android

PROJECT_SOURCE_CODE_BRANCH Android

PROJECT_SOURCE_CODE_REPOSITORY_

CREDENTIALS_ID

Android

PROJECT_WORKSPACE Android

BUILD_MODE iOS

CLOUD_CREDENTIALS_ID iOS

FABRIC_APP_CONFIG iOS

DEFAULT_LOCALE iOS

APPLE_ID iOS

APPLE_DEVELOPER_TEAM_ID iOS

APPLE_SIGNING_CERTIFICATES iOS

IOS_MOBILE_APP_ID iOS

IOS_TABLET_APP_ID iOS

IOS_UNIVERSAL_APP_ID iOS

IOS_APP_VERSION iOS

IOS_BUNDLE_VERSION iOS



Parameter Platform

IOS_DISTRIBUTION_TYPE iOS

APPLE_WATCH_EXTENSION iOS

FORM_FACTOR iOS

PROTECTED_KEYS iOS

RECIPIENTS_LIST iOS

RUN_CUSTOM_HOOKS iOS

PUBLISH_FABRIC_APP iOS

PROJECT_BUILDNUMBER iOS

PROJECT_NAME iOS

PROJECT_SOURCE_CODE_BRANCH iOS

PROJECT_SOURCE_CODE_REPOSITORY_

CREDENTIALS_ID

iOS

PROJECT_WORKSPACE iOS

PROJECT_VMWORKSPACE_PATH iOS

PROJECT_XCODEPROJECT iOS

For more information on Environment Variable parameters, refer Configuring Parameters for Building

a Visualizer App.



4.4.7.2 CustomHook Specific Environment Variables

Property Value

BUILD_SCRIPT URL

BUILD_STEP PRE_BUILD_STEP

HOOK_CHANNEL ANDROID_MOBILE

BUILD_ACTION Execute ANT

HOOK_NAME UpdateXcodeLib

SCRIPT_ARGUMENTS ParameterList

HOOK_SLAVE MacOSXHookAgent01

BUILD_SLAVE MacOSXBuildAgent01

UPSTREAM_JOB_WORKSPACE Workspace Location

Note: The valuesmentioned for all the parameters and properties change dynamically based on

your selection at the run-time.

4.4.7.3 Predefined Platform Binary Locations for Respective Platforms

For retrieving artifacts in post build CustomHooks, use PROJECT_WORKSPACE to get into the

workspace folder and access binaries for a specific channel.

For example:



Binary Location Description

${PROJECT_WORKSPACE}/binaries/android/luavmandroid.apk for Android Mobile

${PROJECT_WORKSPACE}/binaries/androidtablet/*apk for Android Tablet

${PROJECT_WORKSPACE}/binaries/iphone/*.kar for iOS Mobile KAR

${PROJECT_WORKSPACE}/binaries/ipad/*.kar for iOS Tablet KAR

${PROJECT_WORKSPACE}/binaries/universalios/*.kar for iOS Universal KAR

${PROJECT_WORKSPACE}/../temp/${PROJECT_NAME}

/build/server/iphonekbf

for iOS Mobile IPA

${PROJECT_WORKSPACE}/../temp/${PROJECT_NAME}

/build/server/ipadkbf

for iOS Tablet IPA

4.4.7.4 Sample Use-Case Scenario

For example, if you have installed Kony Visualizer 7.3 on your Macmachine. You follow a few manual

steps to build the IPA by extracting the KAR on your Macmachine. During the IPA generation, you

perform additionalmanual settings in the Xcode project to change the deployment target as shown in

the following image.



When youmodify the Xcode Project's General Settings, these settingswill update the projectpbx

(VMAppWithKonylib.xcodeproj/project.pbxproj) file in your local XcodeWorkspace folder. Since you

modified the Deployment Target in the Xcode settings, it internallymodifies the IPHONEOS_

DEPLOYMENT_TARGET key in the projectpbx.

Consider that you have the following ANT Script in your local workspace to update the projectpbx file.

The script finds and replaces the value of the key.

<target name =””

<property name="PROJECT_XCODEPROJECT"

value="VMAppWithKonylib.xcodeproj/project.pbxproj"/>

<property name="lt" value="<"/>

<property name="gt" value=">"/>



<echo message="Updating deployment target" />

<replaceregexp

file="${PROJECT_VMWORKSPACE_PATH}/${PROJECT_XCODEPROJECT}"

match='IPHONEOS_DEPLOYMENT_TARGET(.+?)/string'

replace="IPHONEOS_DEPLOYMENT_TARGET${lt}/key${gt}

${lt}string${gt}${IPHONEOS_DEPLOYMENT_TARGET}

${lt}/string"

flags="gism"

byline="false"/>

</target>

If you want to run this program as part of the AppFactory build during the IPA generation, youmust

hook this program through the AppFactory CustomHookDashboard. But you need the location of the

Xcode Project or the project workspace on AppFactory.

AppFactory exposes all the job build parameters and file-system variables to CustomHooks. You can

directly access these environment variables in the ANT andMAVEN scripts.

Note: The program can be written in any programming language, but, it must be executed by an

ANT or MAVEN script that AppFactory invokes during the execution of the CustomHook in the

build process.

Adding CustomHooks in AppFactory

l You can use the PROJECT_VMWORKSPACE_PATH variable in the ANT file to get the absolute

path of the Xcode project in the AppFactoryWorkspace.

l To update the Deployment Target on Xcode, youmust update the

VMAppWithKonylib.xcodeproj/project.pbxproj file that contains the IPHONEOS_

DEPLOYMENT_TARGET key. You canmake similar changes in the project for custom

requirements using CustomHooks.

l Add the following ANT script to the build.xml file of the CustomHook that contains the logic to

update the IPHONEOS_DEPLOYMENT_TARGET keywith the required versionmentioned in the



SCRIPT_ARGUMENTS.

SCRIPT_ARGUMENTS is passed as the argument during the CustomHook upload.

<project name="default" default="project_xcodesettings_update">

<target name="project_xcodesettings_update">

<property name="PROJECT_XCODEPROJECT"

value="VMAppWithKonylib.xcodeproj/project.pbxproj"/>

<property name="lt" value="<"/>

<property name="gt" value=">"/>

<echo message="Updating deployment target" />

<replaceregexp match="IPHONEOS_DEPLOYMENT_TARGET = (.*);"

flags="gis" byline="true">

<substitution expression="IPHONEOS_DEPLOYMENT_TARGET =

${IPHONEOS_DEPLOYMENT_TARGET};"/>

<fileset dir="${PROJECT_VMWORKSPACE_PATH}"

includes="${PROJECT_XCODEPROJECT}"/>

</replaceregexp>

<replaceregexp

file="${PROJECT_VMWORKSPACE_PATH}/${PROJECT_

XCODEPROJECT}"

match='IPHONEOS_DEPLOYMENT_TARGET(.+?)/string'

replace="IPHONEOS_DEPLOYMENT_TARGET${lt}/key${gt}

${lt}string${gt}${IPHONEOS_DEPLOYMENT_

TARGET}${lt}/string"

flags="gism"

byline="false"/>

<echo message="Updated deployment target to ${IPHONEOS_

DEPLOYMENT_TARGET}" />



</target>

</project>

l Add the build.xml file to a zip file, and upload it to the CustomHookDashboard with the

following parameters.

Binary Location Description

HOOK_NAME DeploymentTarget

HOOK_CHANNEL IOS_MOBILE_IPA_STAGE /

IOS_TABLET_IPA_STAGE

BUILD_ACTION Execute ANT

HOOK_ARCHIVE_FILE Upload the downloaded file

SCRIPT_ARGUMENTS -DIPHONEOS_

DEPLOYMENT_

TARGET=10.0

PROPAGATE_BUILD_STATUS Enable

For more information on CustomHooks, refer Configuring CustomHooks.

4.5 Troubleshooting

This section helps to troubleshoot build and test issues at App Factory console using Jenkins interface.

4.5.1 Downloading Log Files

When a build fails in the Kony App Factory, it gathers the required logs and environment details in a zip

file. These details help the Kony Support team to debug the problem and provide a solution.



You can download these log files and raise a support ticket with the Kony Support team to get help in

resolving the build issues.

You can also extract the zip file to look for the captured data and know the reason for the failures.

1. Navigate to buildVisualizerApp job under Visualizer/Builds sub-folder.

2. Open buildVisualizerApp job and navigate to the failed stage.

You can view the status of the build from the Build History section in the left pane.



3. Click Logs to download a zip file to your local system. Extract the zip file to view the list of logs

generated for the job.

You can view the following build logs that resulted in the failure of the job.



4. TheMustHaves zip file in the folder is the channel on which the project is built. The zip contains

the following log files.

The individual logs related to the channel builds are part of the parent zip file (buildVisualizer).

Note: All the sensitive information such as passwordswill be sanitized as *.

4.5.2 Debugging Build Failure

An administrator should be able to find the root of cause, in a scenario when the last

buildVisualizerApp job fails. The administrator can then review parameters or make appropriate action

to recover a Visualizer build.

1. Navigate to buildVisualizerApp job under Visualizer>> Builds sub-folder.



2. Open buildVisualizerApp job and navigate to the failed stage.

3. Hover your mouse on the failed stage and open Logs.

4. Navigate to Building KitchenSinkApp link.

5. Expand Building KitchenSinkApp group and navigate to the failed build job.



6. Find the failed stage on the opened job.

7. Hover themouse over failed stage and open Logs.

8. Explore the log details and find the reason for failure.



Find error message in Print Message – Failed to create IPA file – as folowing:

01:55:50 Failed to create IPA file - Navigate to the step above

and expend it to look for error of IPA generation



In case, if the error message does not show excessive information, an administrator can

navigate to raw console log of a job that fails. There are several options to display Console

Output. At first, the administrator can navigate to a job and select Console Output from drop-

downmenu under specific job id.



Administrator can now pick the specific job to open and select Console Log form the left panel.

After the Console Output in the last buildVisualizerApp job is run, administrator can scroll down

to the status of jobswere launched by the buildVisualizerApp job. There are two failed jobs for

iOS Mobile and Tablet natives. An administrator can open Console Output of any of jobs listed in

the log below by hoveringmouse over job id and opening Console Output in the drop-down

menu.



When the administrator opensConsole Output, he/shemay look for failure and warning

messages related to a stage and a step particular in the build log.



4.5.3 Debugging Build Failure (Alternative Option)

1. Navigate to Facade job within Visualizer folder.

2. Open specific failed build which shown either unstable or failed.

3. Open Pipeline Steps.



4. Scroll down and find unstable or failed stage.



5. Open Log console, and open Starting building link.

6. Open Pipeline Steps.



7. Find failed stages.

8. Open Console Log and find the reason for failure.



4.6 Auto-Triggered Jobs

Currently, there are two types of auto-triggered jobs: scm-triggered(Watchers) and cron-triggered

(Schedulers).

Every project structure has a folder called Triggers in Visualizer sub-folder. The Triggers folder

contains a job for creation of auto-triggered jobs (createTrigger) and two sub-folders, where the

created jobs are stored.

4.6.1 Configuration for GitHub

Perform the following steps to configure triggers onGIT server side.

1. Open the repository at GitHub in a web browser.

2. Navigate to the Settings of the current repository. Settings tab is not visible if you do not have

necessary permissions.



3. In the Settings page, findWebhooks page link on the left navigation panel. Open theWebhooks

page.



4. Create a newWebhook by clicking Add webhook button on the top right corner.

5. Provide valid login credentials to confirm your authorization, to configureWebhooks.



6. After successful login, Webhooks configuration page opens. AddWebhook at AppFactory

console.



7. Enter the following parameters inWebhook configuration page:

l Compose the Payload URL (mandatory field) based on the following template:

https://<JenkinsURL>/github-webhook/ (last forward slash ismandatory); where

<Jenkins URL>: <protocol>://<domain name>, example - https://ci.kony.com

Jenkins URL format depends on git server type, here is list of examples for currently

supported git servers:

Bitbucket Server (Stash): Payload URL is https://<Jenkins

URL>/github-webhook/AWS CodeCommit - currently there is no

available solution but checkout option.

Other: Rest of the git server implementations use Jenknis

plugin; Generic Webhook Trigger Plugin. In this case the

Jenkins URL has the following format - https://<Jenkins

URL>/generic-webhook-trigger/invoke.

Once payload URL is entered, GitHub automatically checks the https connection and

offers you to disable SSL verification. Ignore thismessage.

l Content type should be selected as application/x-www-form-urlencoded

l Jenkins verification does not require a Secret. Leave the field empty.

l Select Push event option to trigger event by push to repository. Only push of code to

specific branch triggers the buildVisualizer job.



l Active should bemarked by default.

8. After providing the necessary parameters, click Add Webhook button.

9. On successfulWebhook creation, the following screen appears. There ismessage in line with

Webhook that contains Payload URL and events supported (in brackets). For example,

https://konydem-elb-1grn3i04mhuky-1615935478.us-west-1.elb.amazonaws.com/github-

webhook/ and (push).



10. To update or delete aWebhook select the Edit or Delete respectively. For more details on how

to configureWebhooks refer to GitHubWebhookDocumentation.

4.6.2 Configuration for Bitbucket

To enable triggers in Stash/Bitbucket, install the Bitbucket add-onWebhook to Jenkins for Bitbucket.

l Log into your Bitbucket instance as an admin.

l Click the admin drop-down and choose Add-ons. TheManage add-ons screen appears.

l Click Find new add-ons from the left-hand side of the page

l LocateWebhook to Jenkins for Bitbucket using the search option. The results obtained include

app versions compatible with your Bitbucket instance.

l Click Install to download and install your app.

l You're all set! Click Close in the Installed.

For further information about add on, refer to

https://marketplace.atlassian.com/plugins/com.nerdwin15.stash-stash-webhook-

jenkins/server/overview

For configuring triggers on Bitbucket/Stash side perform the following steps:


https://developer.github.com/webhooks


1. Open BitBucket repository in a web browser and navigate to Settings of the targeted repository.

Settings tab is available only if you have necessary permissions.

2. Once Settings page is open, find Hooks link in the settings panel.

3. Open Hooks page. Click Enable button at the right corner of StashWebhook to Jenkins to open

Webhook configurations section.



4. Add Jenkins URL and Repo Clone URL.

Here Jenkins URL is Jenkins home page URL. Repo Clone URL is URL used for cloning of

repository. Trigger Jenkins button can be used to check if you are able to trigger desired

watcher Jenkins job. If successful, click enable button in bottom right corner.



5. For further edit or disableWebhook, we can refer to same section. To edit setting inWebhook,

click on edit icon just after youWebhook.

4.6.3 Configuration for AppFactory Console

To setup auto-triggered job, perform the following steps:



1. Navigate to Triggers folder under root folder of the project.

2. Click on createTrigger job.

3. Provide all required parameters (they are the same as in buildVisualizer job). Please note, that

there is one additional parameter, which is called "CRON_SCHEDULE".



4. A cron-triggered job is created and stored in "Schedulers" subfolder, If "CRON_SCHEDULE"

parameter is provided. Else, an scm-triggered job is created and stored in "Watchers" subfolder.

5. Every Scheduler that is created, has a cron string in job's name to simplify job search. Refer to

Cron Documentation for cron expressions that can be set up in CRON_SCHEDULE

parameter.

6. EveryWatcher created has a branch name in the name of Job to simplify job search.


https://en.wikipedia.org/wiki/Cron


4.6.4 Schedule Nightly Builds

There can be a requirement to build applications at the night on regular base. Nightly builds have

better performance and efficient resource allocation. Also nightly builds are used for solid product build

and testing without ongoing development.

Perform the following steps to configure night builds of any required Visualizer application:

1. Setup Visualizer project as a prerequisite. Refer to Setup section for more details.

2. Once Visualizer project is configured, navigate to the Visualizer folder .



3. Navigate to Triggers folder and click to open it. Triggers folder contains all jobs necessary to

schedule and run Visualizer builds by code changes.

4. Click on createTrigger link to open createTriggers job.



5. Once the createTrigger job is displayed, there are Build with Parameters action on the left

panel. Select Build with Parameters to launch configuration build that generates Schedulers or

Watchers job. See section Configuration for AppFactory console above.

6. Enter all the parameters required for running the Build with Parameters job. Refer to Building

Visualizer app section for more details.



7. Specify without fail the CRON_SCHEDULE parameter corresponding to the

https://en.wikipedia.org/wiki/Cron expression: 0 0 * * * for nightly build. Fill all other parameters

according to standard buildVisualizer job parameters.

8. Once parameters are filled, click on BUILD button to run the createTrigger job.

9. The createTriggers job creates Schedule_0 0 * * * job under Schedulers folder. This specific job

is launched based on CRON_SCHEDULE expression time schedule. Aswe set up 0 0 * * *, it

triggers the Visualizer build with parameters stored in Scheduler_0 0 * * * job and the usual flow

(see section Building Visualizer app) is executed.



4.6.5 Scheduling Custom Builds

Below are the additional scheduling options youmay use to build Visualizer by specific frequency.

1. Setup Visualizer project as prerequisite, as defined in Setup section.

2. Setup Scheduler job as prerequisite, as defined in Scheduling Nightly Builds (Steps 1-6).

3. Select Build with Parameters option on the left panel of createTrigger job and define CRON_

SCHEDULE parameter. For details refer to https://en.wikipedia.org/wiki/Cron.

4. Once all the necessary parameters are filled, press BUILD button to generate scheduler job,

which is triggered based on time set byCRON_SCHEDULE parameter.

5. Once createTrigger finishes successfully, navigate to Schedulers folder to confirm 'Scheduler

job' creation.

4.6.6 Running builds by code change

In addition, an administrator can configure the buildVisualizerApp job for triggering based on the

change in source control. The administrator needs to configureWebhook in accordance with the

Configuration for github or Configuration for Bitbucket. WhenWebhook is configured in project

repository, the administrator needs to configure a watcher job corresponding to Configuration for App

Factory console.

Following scenarios can be automated using watchers:



l An administrator configures a watcher on release branch. A developer merges code changes

from feature branch to release branch. Automatically the buildVisualizerApp job is triggered

when changes appear in the release branch.

l A developer wants to build an App every time he/she pushes changes to source control. The

developer works in specific branch. An administrator configures a watcher that triggers the

buildVisualizerApp job on changes in the dev branch.

l A tester wants to build and test an App for each time the developer pushes changes to source

control into specific branch. An administrator configures a watcher that triggers the

buildVisualizerApp job with device pool, so that, the tester can receive test results on every

code change.

Every scenario depends on a different set of parameters like channels, device pool, branch,

environment (development, staging, production) and other combinations.

4.7 Testing an App - TestNG

AppFactory supports two types of platforms to run the tests.

l Native Tests - Run the Native test cases using Appiumwith TestNG framework.

l DesktopWeb Tests - Run the DesktopWeb test cases using Seleniumwith TestNG framework.

4.7.1 Native Tests

AWS Device farm offers two types of environments to run the tests.

l Standard Test Environment.

l CustomTest Environment

Standard Test Environment - In a standard test environment, the Device Farm provides the logs and

reports for every test case available in the test suite. You can use these logs to locate and fix issues in

your app. You can run these tests in the latest Appium version and a new instance of the application is



built for every test case while running the tests. These test cases are implemented as per the

sequence provided in the test package. As the reports are gathered for everyminor detail of the tests,

it takes some time to run each test case. TestNGannotations and TestNGXML files are not

considered in Standard Testing Environment.

To know more about Standard Test Environment, refer Standard Test Environment.

CustomTest Environment - In a CustomTest Environment, you can use the TestNGannotations to

group, exclude and include the test caseswhich you want to run, and generate the logs and reports

accordingly. You can also use the TestNGXML file to determine the order in which the test should run.

You can download and install the latest Appium version in the device farm environment and run the

tests in it. All the test cases are run in the single instance of the application whichmakes the test

execution faster in this environment. However, the speed of the test execution depends on the logic

and flow of the test cases.

To know more about CustomTest Environment, refer CustomTest Environment.

To know more about the difference between Standard and CustomTest Environments, refer

Standard and Custom test Environments.

Prerequisites

Youmust meet the following prerequisites for testing the application:

l Place the Appium tests at <root folder>/test/TestNG in your Visualizer project.

l The Appium testsmust be compatible with AWS Device Farm, because the Appium tests are

executed in the AWS Device FarmCloud environment.


https://basecamp.kony.com/s/article-detail/a046A00000DNdYRQA1/appfactory-custom-test-environment-run-raw-mode


Note: You can find the Appium tests in the root folder of the project.

l Testsmust be compiled usingMaven and pom.xml available in the Tests root folder (e.g. <root

folder>/test/testNG).



l Make sure that you configure a device pool before you test the application. You can do the

following to configure the device pool:

l Creating Device Pool

Before you start running the tests youmust specify list of mobile devices. These devices are

limited with predefined list that AWS Device Farm supports. To specify devices, navigate to

Tests folder under <project folder>/Visualizer/. Once you are in the Tests folder, verify that you

see all jobs listed as shown in the screenshot below:

Run the Build with Parameters at themanagePool job by clicking on the corresponding icon. The

managePool configuration appears; fill the details. Once you enter the date, you can use

predefined device pool for running tests. There is no limitation for the number of device pools you

can create. The list of devices available in the following screenshot are taken from AWS Device

Farm approved list.



POOL_NAME specifies name of the device pool which will be used in dropdownmenu during

running tests and full build. See Building Visualizer project above.

DEVICE_LIST specifies list of devicemodels for ANDROID, iOS VERSIONS, different

VENDORS, MODELS of PHONES and TABLETS. Youmay use a filter to focus on a specific

MODEL for example



Note: If you select one or more devices using a filter and try to modify your selection by

changing the filter (selecting another set of devices), the previous selection is overwritten

with the current selection.

After filling properties above, submit the device pool by BUILD button. When device pool BUILD

is complete, managePool job passes successfully. Please verify the screenshot below where

Build #1 is green andmarked successfully.



Now, a new device pool has been created and you can run tests either separately or within full

build and tests process.

l Removing Device Pool

A device pool needs to be removed when it is outdated or obsolete. To remove a device pool

perform the following

l Navigate to the folder where the pool is created. <project_root>/Visualizer/Tests.

l Once you are in the Tests folder, verify that all jobs are listed.

l Run the Build with Parameters at themanagePool job by clicking on the corresponding

icon. ThemanagePool configuration appears.

l Upon launch of themanagePool pick a device pool from the drop-downmenu against

AVAILABLE_TEST_POOLS, where all existing device pools are listed. Youmay use a

filter to make selection faster.

l Once device pool is selected press BUILD button. After build pass please verify that build

status is successful as shown at the picture below.



You can see that the selected pool device is removed from the list. See the following

screenshot for more details.

l Updating Device Pool

For adding or removing particular devices from a device pool which are already created, please

remove device pool and recreate new one with correct devices. For more information on how to

create/remove device pool, refer to Creating Device Pool and Removing Device Pool sections.



4.7.1.1 The following fields apply only for running tests on Native channels:

l ANDROID_UNIVERSAL_NATIVE_BINARY_URL specifies the location of Android universal

binaries. URL should be accessible via internet.

l ANDROID_MOBILE_NATIVE_BINARY_URL specify URL to AndroidMobile binary,

generated by build or locally. URL should be accessible via internet. For example, you can

specify URL to S3 taken from email notification sent by Visualizer build job.

l ANDROID_TABLET_NATIVE_BINARY_URL specify URL to Android Tablet binary,

generated by build or locally. URL should be accessible via internet. For example, youmay

specify URL to S3 taken from email notification sent by Visualizer build job.

l IOS_UNIVERSAL_NATIVE_BINARY_URL specified the location of IOS universal binaries.

URL should be accessible via internet.

l IOS_MOBILE_NATIVE_BINARY_URL specify URL to iPhone binary, generated by build or

locally. URL should be accessible via internet. For example, youmay specify URL to S3 taken

from email notification sent by Visualizer build job.



l IOS_TABLET_NATIVE_BINARY_URL specify URL to iPad binary which was generated by

build or locally. URL should be accessible via internet. For example, youmay specify URL to S3

taken from email notification sent by Visualizer build job.

l NATIVE_TESTS_URL specify URL to already compiled test project binaries. This option is

optional and can be skipped. Either this option onGIT parameters should be provided.

l AVAILABLE_TEST_POOLS specifies device pool in drop-downmenu. This device pool needs

to be created upfront to run tests process. If the device pool is empty, the build fails.

4.7.1.2 Standard Test Environment Run

After the device pools are created, the next step for build engineer is to launch tests. There are two

options for triggering tests on AWS Device Farm.We describe herein the first option in which you can

trigger test run independently from overall build process. Also you can include running tests into overall

build flow as described in Building an App section.

Note: Running Tests directly through runTests job independently from overall build process

requires the user to have a Binary URL to be a public URL. Else, it is recommended to run the

tests as a part of build process.

Before running tests youmust build them. Both steps are encapsulated into runTests job that simplify

overall process of the test run.



Follow the steps to configure the parameters to runTests job:

1. Navigate to the tests folder and select runTests job.

The job asmentioned in the previous sections, run the tests on AWS Device Farm.

2. Upon launching the runTests job, Configuration of Parameters appears.

l Fill the parameter values appropriately.

Note: Below each parameter there is text hint as in what needs to be filled. Follow the

text hint and fill the parameter information in the available fields.



o PROJECT_SOURCE_CODE_REPOSITORY_CREDENTIALS_ID specifies

GIT credentials. See section Adding new credentials for more details. Once git

information is entered, test build will is performed automatically before tests run on

AWS Device Farm.

o PROJECT_SOURCE_CODE_BRANCH specifies where tests are stored to the

GIT Repository. Tests should be placed at <repository_root>/[<sub-folder>/]

test/testNG/<source code of tests>, where <repository_root> and <sub-folder>

are configured as described in Setup section.



l After filling in all the required properties set, click BUILD.



l In thementioned example, binaries for Android phone and tablet are provided for testing.

Also, tests binaries are provided as separate bundle in S3.

l Device pool contains the following devices:

o PHONE * ANDROID * Motorola * Nexus 6 * 7.0,

o PHONE * ANDROID * Samsung * Galaxy S6 (Verizon) * 6.0.1,

o PHONE * IOS * Apple * iPhone 5 * 10.0.2,

o PHONE * IOS * Apple * iPhone 8 * 11.0,

o TABLET * ANDROID * ASUS * Nexus 7 - 2ndGen (WiFi) * 6.0,

o TABLET * ANDROID * Samsung * Galaxy Tab 3 Lite 7.0" (WiFi) * 4.2.2,

o TABLET * IOS * Apple * iPad Air * 9.0,

o TABLET * IOS * Apple * iPad Pro 9.7" * 10.3.3

l Upon build start, watch the progress of the build.

l The test run process consist of the following steps:

o Checkout of test project if GIT_BRANCH andGIT_CREDENTIALS are selected.

o Build the test project

o Publish test binaries at S3 according to <S3 bucket>/<project

name>/Tests/runTests/<build number>/KitchenSinkApp_TestApp.zip, for

example https://s3-eu-west-1.amazonaws.com/

konydemo/KitchenSinkApp/Tests/runTests/4/KitchenSinkApp_TestApp.zip

o Fetch binaries to run them in AWS Device Farm

o Create a project in AWS Device Farm



o Create a device pool at AWS Device Farm, taking a device list selected from the

configuration

o Upload test binaries to AWS Device Farm

o Upload application binaries to AWS Device Farm and schedule a run.

o Retrieve the test results. Usually, the test run process takes around 20min. per

each device in the device pool. Only available devices in Device Farm are used for

testing. All unknown devices are skipped. Also, if a particular application binary is

missing, the devices for that particular OS Channel is skipped from the test run.

Note: You can capture screenshots and display them in the email template

under the respective test cases, when the tests are running through AWS

Device Farm. For more information, refer Run AppiumTest Cases for

Visualizer Application through AppFactory.

To know more about writing test cases for native visualizer applications from scratch and running them

through AppFactory using AWS Device Farm, refer Run AppiumTest Cases.


https://basecamp.kony.com/s/article-detail/a046A00000DNS93QAH/run-appium-test-cases-for-visualizer-application-through-appfactory

https://basecamp.kony.com/s/article-detail/a046A00000DNS93QAH/run-appium-test-cases-for-visualizer-application-through-appfactory

https://basecamp.kony.com/s/article-detail/a046A00000DNS93QAH


4.7.1.3 Custom Test Environment Run (Raw Mode)

When you customize the test environment, you can specify the commands to be run by the Device

Farm to execute your tests. Running a test on a CustomTest Environment ensures that tests on

Device Farm run similar to the tests run on your localmachine.

When you run tests in a CustomTest Environment, you do not get the granular reports for each test

case.

In a custom test environment, you can select the Appium version to run your test. All the TestNG

annotations including grouping and parallel tests/methods are supported.

Note: Pleasemake sure to give the latest appium versions like 1.9.0 to the parameter "APPIUM_

VERSION" while running the tests in CustomTest Environment as AWS Device Farm does not

support older versions like 1.7.2 anymore.

Configuring Parameters

Native Testing related Parameters - The following parameters are applicable only if you want to fire

automated tests on native app generated by the protected build.

l RUN_IN_CUSTOM_TEST_ENVIRONMENT click the checkbox to execute tests in Device

Farm onCustomTest Environment. For more information on refer CustomTest Environment

Run.

Note: If the checkbox is not selected, the tests are executed in Standardmode.

l APPIUM_VERSION Enter the appium version to run your tests. Newer version such as 1.9.0

will be installed on the environment as a part of AWS run.

For more information on supported versions of Appium on AWS DeviceFarm, refer Custom

Test Environment Run.



For information on artifacts available in the notificationmail for AWS CustomEnvironment Run,

refer Building an App in AWS CustomEnvironment.

Note: The parameter is valid only if RUN_IN_CUSTOM_TEST_ENVIRONMENT is

selected.

l TESTNG_FILES Path of the TestNG file(s) in your testing JAR. Testng.xml located in the root

of the JAR is selected by default. You can specify the path of your TestNG file.

To specifymultiple TestNG file paths, use comma separated path values such as

kony/Testng.xml, kony/appfactory/Testng.xml, testng.xml has three TestNG

files at different locations to be rendered.

Note: If TestNG file specified in the parameter is not found in the source, the tests will run

independently similar to Standard Test Environment.

Including a testng.xml File in the tests.jar File for Device Farm

In the CustomTest Environment, TestNGXML is used to run the tests in the project test code. To do

this, testing.xmlmust be present in the Testing Jar that is created as part of the test code compilation.

You can configure your test code to package this XML into the Testing Jar as part of themaven build.

Note:l In Device Farm's standard environment, only a subset of features are supported for the

testng.xml file.

l UseCustom environment if the following are required for the project:

l Priority tag

l Include and Exclude tag



l ComplexGrouping

l Parameters from testng.xml file

To apply the testng.xml file to the AppiumTestNG test package for AWS Device Farm, youmust add

the testng.xml file to the root of the *-tests.jar file. To achieve this, do the following:

1. Place your test code in the root test folder that is available at the following locations:

l For SP4 and higher versions, <project_root>/testresources/TestNG/.

l For lower versions, <project_root>/test/TestNG.

Note: Ensure that pom.xml is present in the required directory.

2. Write the required TestNGXML and place it at <root_test_

folder>/src/test/resources location.

3. To explicitly reference a directory, include the testresources tags in the pom.xml.

<testResources>

<testResource>



<directory>${project.basedir}/<root_test_

folder>/src/test/resources</directory>

</testResource>

</testResources>

4. To reference the TestNGXML file for local executions, modify the pom.xml to include the

surefire plugin.

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-surefire-plugin</artifactId>

<version>2.12.4</version>

<configuration>

<suiteXmlFiles>

<suiteXmlFile>src/test/resources/testng.xml</suiteXmlFile></suite

XmlFiles>

</configuration>

</plugin>

Note: For more than one TestNGXML, usemultiple<suiteXmlFile> tags.

5. To verify the package, you can build the test code to create a dependencies zip that contains the

Testing JAR. This zip with the dependencieswill be present inside <root_test_folder>/ target

directory. Package the tests usingmaven clean and package commands at the test root folder.

The -DskipTests=true option specifies that the build should not run the unit tests.

mvn clean package -DskipTests=true

6. Extract the zip folder. To verify whether the TestNGXML file is present at the desired location

(root, by default), extract the jar using xf command.

jar xf nameOfTheProjectFromPom-1.0-SNAPSHOT-tests.jar

Alternatively, you can use the unzip command to extract the contents of the jar.



unzip nameOfTheProjectFromPom-1.0-SNAPSHOT-tests.jar -d

sampletestsjarcontents

If the XML is in the correct location, remove the target folder and check-in the code into a branch in Git.

Now, you can run your tests on AppFactory in the CustomTest Environment.

Note: Steps 3 and 4 are only for verification purpose. Tests will be compiled by AppFactory during

runtime unless the zip with dependencies is directly provided via build parameters.

For more information, please refer to AWS Documentation.

Important: You can use the universal application binary and run the tests on bothmobile and

tablet devices based on the availability in the device pool.

You can trigger a run test job either with universal binary or with individualmobile/tablet.

Important: If you are running the tests individually, public URL must be provided to NATIVE_

TESTS_URL, FABRIC_APP_URL, ANDROID_MOBILE_NATIVE_BINARY_URL,

ANDROID_TABLET_NATIVE_BINARY_URL, IOS_MOBILE_NATIVE_BINARY_URL, IOS_

TABLET_NATIVE_BINARY_URL, and DESKTOPWEB_TESTS URL, ANDROID_

UNIVERSAL_NATIVE_BINARY_URL, IOS_UNIVERSAL_NATIVE_BINARY_URL.

For information on test results, refer to Test Results.

4.7.2 DesktopWeb

Prerequisites

Youmust meet the following prerequisites for testing the application in desktop web:

l The source code that supports DesktopWeb tests is placed at <root

folder>/test/TestNG/DesktopWeb/ in your Visualizer project.


https://aws.amazon.com/premiumsupport/knowledge-center/xml-file-tests-jar-file-device-farm/


l Make sure that the DesktopWeb tests are run using Selenium and TestNG.

l Make sure that you run the tests onGoogle Chrome in headlessmode before running them in

AppFactory.

l If you are running the test through AppFactory, refer the chrome driver path and browser path

as follows during driver initialization:

System.setProperty("webdriver.chrome.driver", System.getProperty

("DRIVER_PATH"));

String browserPath = System.getProperty("BROWSER_PATH");

l If you are using appscommon jar in the test code, you can set driver path and browser path as

follows during driver initialization:

System.setProperty("webdriver.chrome.driver",

sgConfig.getDriverPath());

chromeOptions.setBinary(sg.getKeyValue(browserPath));



where sg is an instance of SgConfiguration class and chromeOptions is an instance of

ChromeOptions.

4.7.2.1 The following fields apply only for tests running on DesktopWeb channels:

l FABRIC_APP_URLEnter the fabric app URLwhere the desktopWeb appWAR is deployed.

l DESKTOPWEB_TESTS_URL allows you to enter the location of the tests binaries of the

Desktop web app.

l AVAILABLE_BROWSERS allows you to select the browser from the drop-down list to run the

DesktopWeb tests.

l RUN_DESKTOPWEB_TESTS_ARGUMENTS allows you to pass any additional arguments

in Maven command to the DesktopWeb tests.

Example: If you pass -Dsurefire.suiteXmlFiles=resources/Testng.xml, the

argument will trigger the tests present in resources/Testng.xml file. If you do not pass

TestNG file, Testng.xml is selected as a default file.

For information on test results, refer to Test Results.



4.7.3 CustomHooks

The following field apply for CustomHooks:

l RUN_CUSTOM_HOOKS Click this check-box if there are hooks defined to run in Post-Test

stage. For more information refer Running CustomHook .

Notifications - The following field is used to configure settings specific to Notifications.

l RECIPIENTS_LIST setting list of e-mails IDs separated by coma, up as recipients of email

notifications.

4.7.4 Running Tests from buildVisualizerApp job

You can also trigger the tests from the buildVisualizerApp job available at Project Name > Visualizer

> Builds folder. It is the simplest way to validate your code by launching tests right after Building the

application. There is no need to specify all parameters as they are provided while running the tests

manually. The results can be viewed in line to the Test Results of Manual Tests.

4.7.5 Test Results

4.7.5.1 Native Tests

When the project test build is complete and the test results are published at S3, e-mail notifications are

sent to recipients:

On Successful test build the following e-mail is sent to the recipients:



On unsuccessful build for the tests run, the following e-mail is sent to the recipients:



In the final stage, the consolidated test run status is notified via e-mail. Refer the following screenshots

for the sample email for consolidated status.

Sample email for Native tests

To download test data fetched fromAWS Device Farm, click Download File link. Data is stored at S3

and available for review without time limitations.

4.7.5.2 Desktop Web

When the project test build is complete and the test results are published at S3, e-mail notifications are

sent to recipients:



OnSuccessful test build the following e-mail is sent to the recipients:

On unsuccessful build for the tests run, the following e-mail is sent to the recipients:



In the final stage, the consolidated test run status is notified via e-mail. Refer the following screenshots

for the sample email for consolidated status.

Sample email for DesktopWeb tests



The summary of the test results are shown based on the tests executed on specified browser that

includes passed, failed, skipped. Usually the tests are skipped when the driver initialization fails.

You can click the respective links in Brief Summary table to view the test summary.

To download the log files for each test case, click the respective Download File link. If you have any

test failures, you can use these files to debug them.

4.7.5.3 Test Status

Test Status is available in the test result email which is sent to the recipient after you execute the test

cases. Following are different statuses in the test result email:

PASSED: The status of the test result is PASSED when the test case is run without any issues, and

when the assertion is successful.

FAILED: The status of the test result is FAILED when the expected result does not match with the

actual result of the test case, the assertion will fail and hence the test case status will be set to FAILED.

SKIPPED: Following are the scenarios where a test case can be skipped while testing, and the status

of the test result can be SKIPPED.

l AWS Issue: AWS skips the test cases yet to run when the duration of the test run exceeds 150

minutes (AWS Device Farm default time limit) resulting in the SKIPPED status. This is

applicable only for Native test results.

l TestNG issue: There are various scenarios where TestNG can skip the test cases during a test

run. Themost common scenario is, if a parent test case fails for any reason, TestNGwill skip all

the related child test cases, and the status of the test result is SKIPPED.

WARNED: The status of the test result isWARNED when the device farm returns anywarning due to

the issues fromAWS.

STOPPED: The status of the test result is STOPPED when you abort the test case forcefully.

ERRORED: The status of the test result is ERRORED when the device farm returns any error due to

the technical issue on AWS.



Note: WARNED, STOPPED, and ERRORED statuses are not applicable for DesktopWeb tests.

4.7.6 Troubleshooting Issues

The following errorsmight help you during troubleshooting runTests job fail:

l Error - Please provide only one option for the source of test scripts: GIT or TESTS_URL:

Solution - Ensure that you provide either SCMdetails or TESTS_BINARIES_URL.

l Error - Please provide pool to test on.

Solution - Ensure that you provide a value to AVAILABLE_TEST_POOLS parameter to run the

native tests.

l Error - Sorry, You can't run test for Android Universal binary along with AndroidMobile/Tablet.

Solution - The universal binary tests both theMobile and Tablet binaries based on the

availability of the devices in the device pool. So it is not required to providemobile/tablet binary

when you give universal binary.

l Error - Build parameter <parameter name> value is not valid URL!

Solution - Ensure that the URL you provide for any of the following parameters is valid:

l ANDROID_MOBILE_NATIVE_BINARY_URL

l ANDROID_TABLET_NATIVE_BINARY_URL

l IOS_MOBILE_NATIVE_BINARY_URL

l IOS_TABLET_NATIVE_BINARY_URL

l NATIVE_TESTS_URL

l ANDROID_UNIVERSAL_NATIVE_BINARY_URL

l DESKTOPWEB_TESTS_URL

l IOS_UNIVERSAL_NATIVE_BINARY_URL



The builds that failed during the test can be tracked for the issues that caused the failure. For analysis

let us consider build #4 test run from the following screenshots of runTests job. Perform the following

steps to troubleshoot the issue

l Navigate to <project folder>/Visualizer/Tests.

l Open runTests job and find the #4 build. Alternatively, find the link #4 rounded within rectangle

and click to open it.



l Once the failed build is open, select the Console Output on the left panel. The Console Output

Log opens on the right pane, for view.

l Scroll down to find errors in the log that caused the build to fail. For the example considered, you

can trace an error related to invalid Android Tablet URL in the following screenshot.



l Check if the ANDROID_TABLET_NATIVE_BINARY_URL parameter is valid.

l To simplify the search for root cause, you can alternatively choose to troubleshoot the issue

from the stages of Manual Testing. For more details see the following screenshot and

corresponding procedure.

l Observe from the screen above that the last build is successful and all process stages are



completed successfully too. However, build #4 failed. Here we have an option to navigate to a

particular failed stage and review the issues there.

Hover your mouse over the Fetch binaries stage of build #4. A new pop-up window is

displayed. Open full log using narrow link as highlighted in the screenshot.

l The logmessages in the Stage Logs window can be expanded to view more details of a single

logmessage. See the image below for more details.



l Identify the error message as Android URL not found. Check for ANDROID_TABLET_

NATIVE_BINARY_URL parameters accordingly.

4.7.7 Auto Triggering Tests

Currently, there are two types of auto-triggered test jobs: scm-triggered(Watchers) and cron-triggered

(Schedulers). Every project structure has folder called "Tests" in "Visualizer" sub-folder, that contains

job for creation of auto-triggered jobs (createTrigger) and two sub-folders where created jobs are

stored.

To setup auto-triggered job, perform the following steps:

1. Go to Tests folder under project's root folder.

2. Click on createTest job.



3. Provide all required parameters (they are the same as in "Facade" job).

Important: Please note, that there is one additional parameter, which is called "CRON_

SCHEDULE". If "CRON_SCHEDULE" parameter is given, then a cron-triggered job is

created and stored in "Schedulers" sub-folder. If the parameter is not provided, a scm-

triggered job is created and stored in "Watchers" sub-folder.



4. Check that the createTest job is complete.



Important: Every Scheduler that is created, will have cron string in job's name to simplify the

job search. Refer the image below.



Important: EveryWatcher that will be created, will have branch name in job's name to

simplify job search.


5. Running Kony Fabric App AppFactory User GuideVersion1.7

5. Running Kony Fabric App

A user can develop Kony Fabric service and publish it to KonyCloud for accessing the service while

connecting to an endpoint from the Visualizer project. After the process is complete, the user is

provided with Kony Fabric app key and secret.

In AppFactory, Kony Fabric functionality is placed in the project folder with corresponding name

Fabric. Navigate to the folder for the Fabric functionality usage. Currently, there are three basic

operationswhich are available for Fabric apps:

l Fabric Export

l Fabric Import

l Fabric Publish

Important: For users on AppFactory pipeline version v8.4.2.1, having Fabric hosted on Azure,

performing fabric operations is not yet supported. The support for such operations is coming as

part of V9 release fromAppFactory.

App Versioning: In Kony Fabric, we havemultiple versions of the same application. AppFactory

supports versioning of the Kony Fabric app during Export (or) Import (or) Publish. App Versioning

feature impacts AppFactory in various scenarios.

Following flowcharts explains the process of export, import, and Publish process in AppFactory.

l Fabric Export: The Fabric export is used to export the existing Kony Fabric application to SCM

(git in our case). The following flow chart explains the process of exporting an application from

Kony Fabric. Upon configuring the parameters in the AppFactory Console for exporting a Kony

Fabric app and clicking the Build button, the following process is performed at the run-time.



The following steps are performed at the run-time to export a Kony Fabric app fromKony

Fabric:

1. During the export process, AppFactory validates certain parameters provided during

configuration like APP_VERSION, BRANCH_NAME, andOVERWRITE_EXISTING.

For detailed information on the parameters, refer Configuring Parameters to Export an

App fromKony Fabric.

2. Upon verifying the parameters, AppFactory checks out the source code and checks for

the branch name.

If the branch name does not exist, the build fails.

3. If the branch name exists, AppFactory verifies the specified app_version.

l If the app version of the build matcheswith the app version of the existing Kony

Fabric app in Git repository branch, AppFactory checks if there are any differences

between both the apps.

o If the differences in the files are found, AppFactory commits and pushes the

changes.



o If the differences are not found, AppFactory commits and pushes the build.

l If the specified app_version does not match with the existing app_version:

o Checks if the OVERWRITE_EXISTING checkbox is selected. (This is done

during the configuration of the Kony Fabric app in AppFactory).

For more information onOVERWRITE_EXISTING, refer Configuring

Parameters to Export an App fromKony Fabric .

n If OVERWRITE_EXISTING is selected, AppFactory removes the old

files and commits new files.

n If OVERWRITE_EXISTING is not selected, the build fails.

l Fabric Import: The Fabric Import is used to import an app fromSCM to Kony cloud. User must

configure few parameters to publish an imported Fabric app or execute a publish job. After

configuring the parameters and clicking the Build button, the following process is performed at

the run-time.

The following steps are performed at the run-time to import an app to Kony Fabric:



1. During the import process, AppFactory validates certain parameters provided during

configuration like APP_VERSION, BRANCH_NAME, andOVERWRITE_EXISTING.

For detailed information on the parameters, refer Configuring Parameters to Import an

App to Kony Fabric.

2. Upon verifying the parameters, AppFactory checks out the source code and checks for

the branch name.

If the branch name does not exist, the build fails.

3. If the branch name exists, AppFactory verifies the specified app_version.

l If the specified app_version does not match with the Fabric app_version available

in SCMat the specified branch, the build fails.

l If the app version of the build matcheswith the app version of the existing Kony

Fabric app, the AppFactory checks if the OVERWRITE_EXISTING checkbox is

selected. (This is done during the configuration of the Kony Fabric app in

AppFactory).

For more information onOVERWRITE_EXISTING, refer Configuring Parameters

to Import an App to Kony Fabric .

o If OVERWRITE_EXISTING is selected, AppFactory imports the app as an

old version in Fabric.

o If OVERWRITE_EXISTING is not selected, a new app version is imported

to Fabric.

l Fabric Publish: The Fabric Publish is used to publish an existing application to a specific

environment.



The following steps explains the process of publishing an application in Fabric to a specific

environment.

1. During the publishing process, AppFactory validates certain parameters provided during

configuration like APP_VERSION and SET_DEFAULT.

2. After validating the parameters, AppFactory publishes the app in Fabric.

3. If SET_DEFAULT is selected, the specified App_version is set as default in Fabric.

You can publishmultiple versions of Fabric applications in same app. But your visualizer

application uses the services of a specific version in Fabric, that is set as a default version.

Tomake the published Fabric version as the default version, select the SET_

DEFAULT check boxwhile configuring the Fabric parameters.

5.1 Kony Fabric Export

The Kony Fabric export is used to export the existing Kony Fabric application to SCM (git in our case).



The export job keeps track of the application code that is exported in the previous build. If there are no

changes from the previous build, the push part of the pipeline is omitted.

5.1.1 Configuration

The following parameters appear when the user selects Build with Parameters job action.

1. Related to Source Control

l PROJECT_EXPORT_REPOSITORY_URL is a repository URL required to point SCM

client where to push your application code.

The URL format is https://server/<path to repo>.git

l PROJECT_EXPORT_REPOSITORY_CREDENTIALS_ID are required to access the

repository and choose where you want to store your application code.

l PROJECT_EXPORT_BRANCH is required to point the SCM client to the branch that

pushes your application code.

2. Related to Commit details

Commit related are required for SCM client, these parameters help to compose commit.



l AUTHOR_EMAIL - Email of the author who peforms changes to the app in source

control.

l COMMIT_AUTHOR - A user name on behalf of commit is pushed to the source control.

l COMMIT_MESSAGE - A message to be put into source control.

l OVERWRITE_EXISTING - Click the checkbox to force push to selected branch.

Selecting the checkboxwill overwrite the app content.

3. Related to Kony Fabric

l CLOUD_CREDENTIALS_ID - Kony cloud credentials.

l CLOUD_ACCOUNT_ID - Kony cloud account ID.

l FABRIC_APP_NAME - Name of the Kony Fabric application that needs to exported (or)

imported (or) published.

l FABRIC_APP_VERSION is the version of Kony Fabric project. The default version is

1.0.



4. RECIPIENTS_LIST - Enter the e-mail addresses separated by comma to notify people of the

job results.

5.1.2 Exporting

Once all the parameters are set, export can be triggered with BUILD button. Exporting process

contains the following stages:

l Prepare the build node environment.

l Export Kony Fabric application

l Check if there were changes

l Clone Kony Fabric application fromGit

l Configure local Git account

l Prettify exported JSON files andmove them to SCM

l Push changes to remote storing artifacts

l Notify on export status by email



On successful export, the designated user receives an email alert.

On unsuccessful export, the designated user receives an email alert on export failure.



5.2 Kony Fabric Import

Import job is responsible for uploading a Kony Fabric app fromSCM to KonyCloud. In addition, import

job can publish a Kony Fabric app right after its upload to KonyCloud. Refer parameters to specify, if a

user wants to publish a Kony Fabric app or execute a publish job (see below).



5.2.1 Configuration

The following parameters appear when a user selects 'Build with Parameters' job action.

1. Related to Source Control

l PROJECT_EXPORT_REPOSITORY_URL is a repository URL required to point SCM

client where the Kony Fabric application code is checked.

l PROJECT_EXPORT_REPOSITORY_CREDENTIALS_ID is required to access the

repository and choose the stored Kony Fabric app.

l PROJECT_EXPORT_BRANCH is required to point the SCM client to the branch where

the Kony Fabric application code is checked-in.

2. Import Options

l OVERWRITE_EXISTING - parameter required for overriding application if it’s already

present in Kony Fabric.

l ENABLE_PUBLISH - Once Import job execution finishes, ENABLE_PUBLISH

parameter is triggered to publish the job.



3. KONY FABRIC RELATED


l CLOUD_ACCOUNT_ID - Kony account ID.

l FABRIC_APP_NAME - An application ID in Kony Fabric (in most of the cases it is same

as application name).

l FABRIC_APP_VERSION is the version of Kony Fabric. The default version is 1.0.

l FABRIC_ENVIRONMENT_NAME - An environment name in Kony Fabric to publish the

Kony Fabric application.

4. RECIPIENTS_LIST - Enter the email addresses separated by a comma to notify the people

about the job results.

5.2.2 Importing

Once all the parameters are set, trigger import with BUILD button. Importing process contains the

following stages:



l Prepare the build node environment

l Import Kony Fabric application

l Clone Kony Fabric application from git

l Create zip file of Kony Fabric git project

l Notify on import status by email

On successful import, the designated user receives an email alert with success details.



On unsuccessful import, designated user receives an email alert with failure details.



5.3 Kony Fabric Publish

Publish job is responsible for publishing the existing Kony Fabric application to a specific environment.

5.3.1 Configuration

The following parameters appear when a user selects build with parameters job action.

Publish job uses only Kony Fabric group of job parameters with one additional parameter:

1. KONY FABRIC RELATED


l CLOUD_ACCOUNT_ID - Kony account ID.

l FABRIC_APP_NAME - An application ID in Kony Fabric (in most of the cases, it is the

same as application name).

l FABRIC_APP_VERSION - Enter the Kony Fabric app version to export.

l FABRIC_ENVIRONMENT_NAME - An environment name in Kony Fabric. The

environment needs to be linked with Kony Fabric services.

l SET_DEFAULT_VERSION - Click the checkbox tomake the version specified at

Fabric_App_Version field as a default version for your app.



2. Notifications

l RECIPIENTS_LIST - Enter the email addresses separated by a comma to notify the

people about the job results.

5.3.2 Publishing

Once all the parameters are set, trigger publish using BUILD button. Publishing process contains the

following stages:

l Prepare the build node environment

l Publish Kony Fabric application

l Notify on Import status by email



On successful import, the designated user receives an email alert with the success details.

On unsuccessful import, the designated user receives an email alert with failure details.



5.4 Publishing a Web App

A developer can build and publishWeb App (SPA) to KonyCloud.Web App is hosted in AWS based

KonyCloud, accessible by the link given during publishing. Following instructions helps to configure,

build and publishWeb App.

5.4.1 Prerequisites

AWeb App need to be publishedmanually, before configuration of the buildVisualizerApp job with

SPA related parameters. The following steps help to publish SPAmanually.



1. Launch Visualizer and import the KichenSink Application.

2. Launch Visualizer and click on Login button to sign-in into Kony Fabric.

3. Enter Username and password. Upon successful login, you can see the default cloud along side

your Username.



4. If you have access tomultiple clouds. Click on setting ->Click onMobile Fabric Tab >>Choose

desired cloud and environment.



5. Click on Kony Fabric and choose Use Existing button, if an app already exists in MF. If not, click

Create button and can createMF app.



6. Choose the app you need and click on ASSOCIATE button.

7. Once that is done, build the SPA build.



8. Upon successful build, go to file -> Publish to Kony Fabric.

9. MF console opens in Visualizer. Select Publish tab, and click Publish.



5.4.2 Adding New Credentials

Perform the following steps to add new credentials for the buildVisuazlierApp job. Credentials are

given in the format of Username, password and id/description if necessary.

1. Press Add button.

2. Choose Credential provider from the list. It varies from the level at which entered credentials

are visible. Select project root folder, for example KitchenSinkApp

3. Enter Username and Password and click Add.



4. Select from the list the credentials that are created just now.

5. Check the selected credentials

5.4.3 Configuration

A developer want to build and publish aWeb App. For that reason he/she needs to configure the

buildVisualizerApp job. Perform the following steps to configureWeb App build and publish

parameters.



1. Open an app project folder and navigate to Visualizer/Builds/buildVisualizerApp.

2. Launch the buildVisualizerApp job using Build with parameters action.

3. SetWeb App related parameters. See Configuration section for more details on each

parameter. Parameters should be set accordingly to Configuration of the buildVisualizerApp

job.



5.4.4 Publishing

When all parameters are set, click BUILD to build and publish aWeb App (SPA). Build starts and you

can see progress as shown in the screenshot below.

Once build is completed successfully, e-mail notification is sent. In addition, the following e-mail is sent

by Kony Support on publishing results.



TakeMobile Application URL and open it in browser selecting specific devicemodel.

Now theWeb App is published to your environment.



5.5 Kony Fabric Triggers

AppFactory enables users to schedule Fabric Import, Export, andMigrate jobs for Kony Fabric app

configurations. In AppFactory project, you can create triggers for Visualizer and Fabric projects. To

create Fabric Triggers, navigate to Triggers in Fabric. The Fabric Triggers has the new trigger jobs for

each Fabric task (such as createExportTrigger, createImportTrigger, and createMigrationTrigger) and

Schedulers. The Schedulers will have the created triggers.

5.5.1 Schedule Export

You can create a trigger to automate the export process of Fabric app configuration by using the

createExportTrigger job. The job enables AppFactory users to create schedulers to automate the

export of Fabric app configuration from Fabric app to SCM.

To set up an auto-triggered job for exporting the Fabric app, perform the following steps:

1. Navigate to AppFactory Project >>Fabric>> Triggers. The Triggers page appears.

2. Click createExportTrigger.



3. Specify all the required parameters.

CRON_SCHEDULE - Specify the UNIX cron-like feature to periodically execute and build your

Fabric task. The field ismandatory as AppFactory allows you to create Schedulers only for

Fabric triggers.

Source Control - You can use the parameters to export or import a Kony Fabric project to/from

the provided repository.

l PROJECT_SOURCE_CODE_REPOSITORY_URL - Repository URL for exporting

the source code of the project; currently, only https URL format is supported.

l PROJECT_SOURCE_CODE_BRANCH - Repository branch name, commit ID, or tag

for Fabric export.



l PROJECT_SOURCE_CODE_REPOSITORY_CREDENTIALS_ID -Used to access

the repository for export and import tasks.

Important: Provide Git credentials depending on theGit URL format. If you provide

the https link, then user credentials (user name and password) are sufficient. For the

case of ssh link, youmust add the ssh key.

Note: If your repository is protected with 2fa in GitHub, add the credentials by using

the secret text method. For detailed information on how to add credentials, refer

Adding New Source Code Repository Credentials.

Fabric - Used to configure settings specific to Kony Fabric.

l CLOUD_CREDENTIALS_ID - Kony cloud credentials. For more information on adding

Kony cloud credentials, refer Adding Cloud Credentials.


l FABRIC_APP_NAME - Fabric application name that needs to be exported.

l FABRIC_APP_VERSION - Fabric app version to export. Only specified version is used

for the export process.



Note: Version input should be in the format of major.minor, wheremajor andminor

are numbers and 1 <= major <= 999 and 0 <= minor <= 99. For example, '1.0' or

'999.99'.

Export Options - Used during the Fabric application export process.

l OVERWRITE_EXISTING_SCM_BRANCH - Select the check box to overwrite the

existing SCM branch.

Note: Selecting the option will overwrite the app content that exists in the given

branch with the latest exported Fabric app content.

l AUTHOR_EMAIL - For GIT client configuration, provide the email ID to push changes to

remote repository.

l COMMIT_AUTHOR - Provide author for commit. The AppFactory value is set by

default.

l COMMIT_MESSAGE - Providemessage for commit. The auto-generated text is set by

default.

Notifications - Used to configure settings associated with notifications.



l RECIPIENTS_LIST - Enter the email addresses separated by a comma to notify people

about the build status. If this parameter is empty, emails will be sent to the Jenkins Default

Recipients list.

4. Click Build to build the Export Trigger job with the build parameters. A cron-triggered job is

created and stored in the Schedulers sub-folder.

Every created Scheduler, has a cron string in the job's name to simplify the job search. Refer

Cron Documentation for cron expressions that you can set up in the CRON_SCHEDULE

parameter.

5.5.2 Schedule Import

You can create a trigger to automate the import activity of Fabric app configuration by using the

createImportTrigger job. The job enables AppFactory users to create the schedulers to automate the

import of Fabric app configuration fromSCM repository to the Fabric app.

To set up an auto-triggered job for importing the Fabric app, perform the following steps:




1. Navigate to AppFactory Project >>Fabric>> Triggers. The Triggers page appears.

2. Click createImportTrigger.



3. Specify the following parameters:

CRON_SCHEDULE - Specify the UNIX cron-like feature to periodically execute and build your

Fabric task. The field ismandatory as AppFactory allows you to create Schedulers only for

Fabric triggers.

Source Control - Used to export or import a Kony Fabric project to/from the provided repository.

l PROJECT_SOURCE_CODE_REPOSITORY_URL - Repository URL for exporting

the source code of the project; currently, only https URL format is supported.

l PROJECT_SOURCE_CODE_BRANCH - Repository branch name, commit ID, or tag

for Fabric export.

l PROJECT_SOURCE_CODE_REPOSITORY_CREDENTIALS_ID - Used to access

the repository for export and import tasks.

Important: Provide Git credentials depending on theGit URL format. If you provide

the https link, then user credentials (user name and password) are sufficient. For the

case of the ssh link, youmust add the ssh key.



Note: If your repository is protected with 2fa in GitHub, add the credentials by using

the secret text method. For detailed information on how to add the credentials, refer

Adding New Source Code Repository Credentials.

Fabric - Used to configure settings specific to Kony Fabric.

l CLOUD_CREDENTIALS_ID - Kony cloud credentials. For more information on adding

Kony cloud credentials, refer Adding Cloud Credentials.


l FABRIC_APP_NAME - Fabric application name that needs to be exported.

l FABRIC_APP_VERSION - Fabric app version to be exported. Only the specified version

is used for export.

Note: Version input should be in the format of major.minor, wheremajor andminor

are numbers and 1 <= major <= 999 and 0 <= minor <= 99. For example, '1.0' or

'999.99'.

Import Options - Used to overwrite the existing application during the import process and

publish the application after successful import.



l OVERWRITE_EXISTING_APP_VERSION - Select the check box to overwrite the

existing Fabric app.

l ENABLE_PUBLISH - Select the check box to publish the application after successful

import.

l FABRIC_ENVIRONMENT_NAME - Provide the Fabric environment for publishing.

l SET_DEFAULT_VERSION - Select the check box tomake the specified version in the

FABRIC_APP_VERSION field as the default version for your app.

Notifications - Used to configure settings specific to notifications.

l RECIPIENTS_LIST - Enter the email addresses separated by a comma to notify people

about the build status. If this parameter is empty, emails will be sent to the Jenkins Default

Recipients list.

4. Click Build to build the Import Trigger job with the build parameters.

A cron-triggered job is created and stored in the Schedulers sub-folder.



Every created Scheduler has a cron string in the job's name to simplify the job search. Refer

Cron Documentation for cron expressions that can be set up in the CRON_SCHEDULE

parameter.

5.5.3 Schedule Migrate

You can create a trigger to automate themigration activity of the Fabric app configuration by using

createMigrationTrigger job. The job enables AppFactory users to automate themigration of Kony

Fabric App configurations from one environment to another Fabric environment by using schedulers.

To set up an auto-triggered job for migrating the Fabric app, perform the following steps:

1. Navigate to AppFactory Project >>Fabric>> Triggers.. The Triggers page appears.




2. Click createMigrationTrigger.

3. Specify the following parameters:

CRON_SCHEDULE - Specify the UNIX cron-like feature to periodically execute and

build your Fabric task. The field ismandatory as AppFactory allows you to create

Schedulers only for Fabric triggers.

Source Control - Used to export or import Kony Fabric project to/from the provided

repository.

l PROJECT_SOURCE_CODE_REPOSITORY_URL - Repository URL for

exporting the source code of the project; currently, only https URL format is

supported.



l PROJECT_SOURCE_CODE_BRANCH - Repository branch name, commit ID,

or tag for the Fabricmigrate.

l PROJECT_SOURCE_CODE_REPOSITORY_CREDENTIALS_ID - is used to

access the repository for export or import tasks.

Important: Provide Git credentials depending on theGit URL format. If you

provide the https link, , then user credentials (user name and password) are

sufficient. For the case of the ssh link, youmust add the ssh key.

Note: If your repository is protected with 2fa in GitHub, add the credentials

using the secret text method. For detailed information on how to add the

credentials, refer Adding New Source Code Repository Credentials.

Fabric App Details For Migrate - Used to configure the settings specific to the Kony

Fabric app for migration.

l FABRIC_APP_NAME - Name of the Fabric application that needs to bemigrated.

l FABRIC_APP_VERSION - The Fabric app version that is to bemigrated. Only the

specified version is used for migration.

Note: Version input should be in the format of major.minor, wheremajor and

minor are numbers and 1 <= major <= 999 and 0 <= minor <= 99. For

example, '1.0' or '999.99'.



Fabric Cloud Details for Export - Used to configure the settings specific to Kony Fabric

Export.

l EXPORT_CLOUD_CREDENTIALS_ID - Kony cloud user name or password for

export. For detailed information on adding cloud credentials, refer Adding New

Cloud Credentials.

l EXPORT_CLOUD_ACCOUNT_ID - KonyCloud account ID for export.

Export Options - Use the following fields during the Fabric application export process.

l OVERWRITE_EXISTING_SCM_BRANCH - Select the check box to overwrite

the existing SCM branch.

Note: Selecting the option overwrites the app content that exists in the

specified branch with the latest exported Fabric app content.

l AUTHOR_EMAIL - For GIT client configuration, provide the email ID to push the



changes to the remote repository.

l COMMIT_AUTHOR - Provide the author for commit. AppFactory value is set by

default.

l COMMIT_MESSAGE - Provide themessage for commit. The auto-generated

text is set by default.

Fabric Cloud Details For Import- Used to configure the settings specific to Kony Fabric

Import.

l IMPORT_CLOUD_CREDENTIALS_ID - KonyCloud user name and password

for import. Click Add to add cloud credentials. For detailed information on adding

cloud credentials, refer Adding New Cloud Credentials.

l IMPORT_CLOUD_ACCOUNT_ID - KonyCloud account ID for import.

Import Options - Used to overwrite the existing application during the import process and

publish the application after successful import.

l OVERWRITE_EXISTING_APP_VERSION - Select the check box to overwrite the

existing Fabric app.



l ENABLE_PUBLISH - Select the check box to publish the application after successful

import.

l FABRIC_ENVIRONMENT_NAME - Provide the Fabric environment for publishing.

l SET_DEFAULT_VERSION - Select the check box tomake the specified version in the

FABRIC_APP_VERSION field as the default version for your app.

Notifications - Used to configure settings specific to notifications.

RECIPIENTS_LIST - Enter the email addresses separated by a comma to notify people for

build status. If this parameter is empty, emails will be sent to the Jenkins Default Recipients list.

4. Click Build to build theMigrate Trigger job with the specified build parameters.

A cron-triggered job is created and stored in the Schedulers sub-folder.

Every created Scheduler, has a cron string in the job's name to simplify the job search. Refer

Cron Documentation for cron expressions that can be set up in the CRON_SCHEDULE

parameter.



6. Working with AppFactory AppFactory User GuideVersion1.7

6. Working with AppFactory

Working with AppFactory section explains the global settings that can be performed in the AppFactory

Console. You canmodify the project settings, permissions to the users, add new credentials, edit and

delete the existing credentials.

6.1 Adding New Credentials

6.1.1 Adding New Cloud Credentials

Perform the following steps to add new credentials for the buildVisualizerApp job. Credentials are

given in the format of Username, password and id (or) description if necessary.

1. Click Add drop-down list.

2. Select a Credential Provider from the list. It varies from the level at which entered credentials

are visible. Select project root folder, for example KitchenSinkApp.

The Add Credentials window appears.



3. Enter the following details to add credentials:


l Kind: Choose kind asUsername with Password from the drop-down list.

l Scope: Determineswhere the credentials are used. The scope is defined as two types:

o System: The credential is available to the object on the associated credential.

System-scoped credentials are used for email, auth, slave connection and so on

(i.e. where the Jenkins instance is using the credential).



o Global: TheGlobal credential is available to the object on which the credential is

associated and all the child objects of the object. Typically, you would use the

global-scoped credentials for the things that are needed for jobs.

l Enter Username and Password.

l Enter ID. It is an internal unique ID used to identify the credentials from jobs and other

configuration.

Note: If the ID field is left blank, an ID will automatically be generated for jobs created

using visual forms. It is recommended to specify ID when using credentials from the

scripted configuration.


Note: Description is an optional field.

l Click Add. The new credentials is added to the list of credentials.

4. Click the drop-down list besides CLOUD_CREDENTIALS_ID. Select the new credentials

created from the list of credentials.

5. Check the selected credentials



6.1.2 Adding new Kony Fabric App Config

Perform the following steps to add Kony Fabric App configuration for building a Visualizer app. This

credentials provider allows you to specify details like app name, account ID or OnPremConsole and

Identity Urls. These details are used further to generate Kony Fabric app config file, and publish web-

app.

1. Click Add drop-down list.

2. Select the Credential Provider from the list. It varies from the level at which entered credentials

are visible. Select project root folder, e.g. KitchenSinkApp

The Add Credentials window appears.



3. Enter the following details in the Add Credentials window:


l Choose Kind as Kony Fabric Configuration.



4. Based on the Domain and Kind selected, the respective fields are displayed as follows:


configuration.






l Environment Name: Enter the Kony Fabric environment name to which the application is

published.

l Application Name: Enter the name of the Kony Fabric application.



l Account ID

o It identifies the Kony Fabric Cloud that is associated with the published Fabric

application. Fabric application uses the Account ID to construct the service URL of

the Fabric application.

o Ideally, the AppFactory assumes that the Fabric app is a part of the account in

which the AppFactory is running. Alternatively, publish the Fabric app to another

account and provide the Account ID in the Fabric App Config details.

Note: The Account ID must always be the same as the Account ID in the Service

URL that is generated after the app is published.

For more information on Account ID, refer the Help section of the field.

l Console URL: It is a publicly accessible URL for your Kony Fabric Console (without

context path), relevant for on-premise installation only. For example,

http://10.10.24.78:8081.

It works as an alternative (along with identity services url) to the Account ID for Kony

Fabric OnPrem installations. For Kony Fabric Cloud, by default, the value points to user's

cloud URL.

l Identity URL: It is a publicly accessible url for your Kony Identity Services (without context

path), relevant for on-premise installation only. For e.g. http://10.10.24.79:8080.

It is amandatory parameter along with Console Url to be used for Kony Fabric OnPrem

installations. Like Console Url, this parameter also points to user's cloud url by default .

Note: Console URL and Identity URL are only valid for on-premise and Azure

installations of Fabric. User should not update these fields unless linking of an

OnPremFabric app with Visualizer app binary is intended.

5. After validating the details, click Add on the Add Credentials window. The new Kony Fabric App

Config credentials are created.

6. Select from the list of credentials that are created just now.



7. Check the selected credentials.

6.1.3 Adding New Source Code Repository Credentials

Perform the following steps to add new source code repository credentials for the buildVisualizerApp

job. Credentials are given in the format of Username, password and id (or) description if necessary.

1. Click Add drop-down list displayed across PROJECT_SOURCE_CODE_REPOSITORY_

CREDENTIALS_ID.

The drop-down list displays the list of Credential Providers.





3. Enter the following details to add a new source repository credentials:


l Choose Kind asUsername with Password from the drop-down list.

If your repository is protected with 2fa in GitHub, add the credentials using secret text

method. To add the credentials using secret text method, choose Kind as Secret Text.












configuration.






l Click Add. The new credentials is added to the list of credentials in buildVisualizerApp

project.



4. Click PROJECT_SOURCE_CODE_REPOSITORY_CREDENTIALS_ID drop-down list.

You can find the new credentials in the drop-down list.

5. Select the new credentials.

6.1.4 Adding New APPLE_ID Entries

Perform the following steps to add a new Apple_ID repository credentials for the buildVisualizerApp

job. Credentials are given in the format of Username, password and id (or) description if necessary.

1. Click Add drop-down list displayed across APPLE_ID.

The list of Credential Providers displays.





3. Enter the following details to add new source repository credentials:


l Kind: Choose Kind asUsername with Password from the drop-down list.












configuration.






l Click Add. The new credentials is added to the list of credentials in buildVisualizerApp

project.

4. Click Apple_ID drop-down list.

You can find the newly added credentials in the drop-down list. Select the credentials.



6.1.5 Adding New Android_KeyStore Credentials

The keystore file is created to store the key that will be used to sign the Android binary. Perform the

following steps to add Android_KeyStore entries for building a Visualizer app. The entries include

Android_Keystore file and Android_KeyStore password.

6.1.5.1 Creating a New Android_KeyStore File

To create Android_KeyStore File, follow these steps:

1. Click Add drop-down list displayed across ANDROID_KEYSTORE_FILE.


2. Select a Credential Provider from the list. The Add Credentials window displays.

3. Enter the following details to add a new credential:


l Choose Kind as Secret file.










l Select a Key Store file.


configuration.






4. Click Add. The new Android_KeyStore file is added to the buildVisualizerApp project.



6.1.5.2 Creating a New Android_KeyStore Password

For every keystore file created, a passwordmust be added.

To create Android_KeyStore Password, follow these steps:

1. Click Add drop-down list displayed across ANDROID_KEYSTORE_PASSWORD.


2. Select a Credential Provider from the list. The Add Credentials window displays.

3. Enter the following details to add credentials:


l Choose Kind as Secret text.



l Enter Secret Text.


configuration.






4. Click Add. The password for the new Android KeyStore file is added to the buildVisualizerApp

project.

6.2 Deleting Credentials

To delete the existing credentials, perform the following steps:



1. Log in to AppFactory Console using your KonyCloud account credentials.

2. Click Credentials from the left pane. It displays the list of credentials added till date.

3. Select the credentials to delete. The detailed page of the selected credentials appears.



4. Click Delete from the left pane. A confirmationmessage is displayed.

5. Click Yes to delete.

Note:Do not delete the following three SSH credentials as these are system driven credentials.

l jenkins_github_ssh-certificates

l jenkins_github_ssh-kony-common

l jenkins_github_ssh-kony-jenkins-job-DSL


7. Results AppFactory User GuideVersion1.7

7. Results

You can review the build and test results from the Jenkins console and Testing console locations,

directly in S3, by email.

7.1 Reviewing Results at Jenkins Console

Upon successful login into Jenkins console, you need to navigate to the project you are building or

testing.

The buildVisualizerApp job is unstable and is denoted by a corresponding icon on the left side. You

can also see an error message specifying the stage that failed. Youmay troubleshoot the issues

following instructions at Troubleshooting section.



7.2 Reviewing Results at Testing Console

You can log intoMF console and open Testing console in AppFactory environment using your

developer credentials. Navigate to the project list and select required project for analysis. If you refer to

build statistics, you see a list of jobs build with a link to original HTML template (with build artifacts at

S3). Also, refer to test statistics for finding information on test jobswith test artifacts at S3.

7.3 Reviewing Results by Email

The developer receives email notificationswhen the build and tests are complete. For more details

refer Building an Visualizer or Kony Fabric App and Testing sections.

7.4 Known Issue

l Creation of CustomHooks view at Jenkins level is not supported.

l If you run the test on both android and iOS devices in a single build, youmay get the following

error due to the jenkins limitation. Try to run the test in separate builds, one for android and one



for iOS, to resolve the issue.

7.5 Limitations

l In AWS Device farmwe have a limitation of 150minutes for test execution. If the execution time

exceeds this limit, the remaining tests are skipped

l V8 SP3 features are not displayed on existing projects in AppFactory Console. Tomake use of

the new features, you must create a new project from this console.

l Currently, AppFactory is not supporting wild card provisioning profiles.

l Due to internal tool dependency, AppFactory Fabric does not allow migrating to a different

version or creating a new version (that does not exist in Project zip/MF Console app).

l With new XCODE 11, when you trigger an iOS build using an Apple ID, by default, the iPHONE



CERTIFICATES are generated instead of Apple Certificates. There will not be any affect on the

functionality of the application and it will continue to work as usual.


kony appfactory user guide · appfactoryuserguide version1.7 5.5konyfabrictriggers 185...

Documents