Custom Build Configuration

From the 202401 release, App Factory supports the configuration of Custom Build Parameters for a Visualizer project through a YAML Configuration file.

If you have multiple custom hooks configured in your Visualizer app, it might cause difficulty in maintaining the custom hooks for each phase in the build flow.
Instead of having to maintain multiple custom hooks, you can configure the custom build parameters for each phase in the build process in a YAML file, that will be executed during the Visualizer Build process.

To access the Custom Build Configuration page, open the Visualizer folder of your App Factory project, and then select Custom Build Configuration from the left panel.

The Custom Build Configuration page consists of a code editor to configure the build parameters in a YAML Configuration file, and the following buttons:

Copy - Use the Copy button to copy the code from the code editor. You can copy the default code and make the required updates in a text editor of your choice, and then paste the updated code in the YAML Configuration section.

Save & Exit - Use the Save & Exit button to save your changes to the YAML Configuration file, and exit the Custom Build Configuration page. The updates in the file are saved, and the file will be executed as part of the Visualizer App Build process.

Cancel - Use the Cancel button to exit the configuration process. Any changes that you have made in the YAML Configuration file will be lost when you cancel the configuration process.

Build Phases

Phases are the execution points during the build flow cycle on which certain collection of commands can be executed.

You can execute Custom Build Parameters at the following four phases of the build flow in App Factory:

PRE_BUILD - Runs the Custom Build Parameters after the initiation of the Build process and before the initiation of the CI process.
POST_BUILD - Runs the Custom Build Parameters after the execution of the CI Build process.
PRE_TEST - Runs the Custom Build Parameters before the Test process is initiated.
NOTE : Channel names like ANDROID_MOBILE_NATIVE etc. do not apply for tests.
POST_TEST - Runs the Custom Build Parameters after the execution of the Test process.

NOTE: You do not need to provide channel names for Test Builds such as PRE_TEST and POST_TEST Builds.

Operations

Operations are a list of pre-defined operations (or steps) in App Factory, that you can execute in a certain stage of a build.

Before you start configuring the operations, you must define the channels for which the operations must be performed.

NOTE:

If you want to perform the operations for multiple channels, you can provide the list of channel names in a group.
You do not need to provide channel names for Test Builds such as PRE_TEST and POST_TEST Builds.

Following are a few examples of valid channel names:

["ANDROID_MOBILE_NATIVE", "IOS_TABLET_NATIVE", "RESPONSIVE_WEB"]
["ALL"]
["ANDROID_MOBILE_NATIVE"]

For each build phase, you can perform the following operations through custom build parameters:

Copy
Delete
UpdateJSON
Replace

Copy

Copies files or directories from one location to another, based on the UNIX paths and arguments.

Code Syntax

 - copy:
     src: <source-path>
     dest: <destination-path>
     args: <arguments>

Example

Path: ws/path/to/file
Argument: -r

Delete

Deletes files or directories from a specified location, based on the UNIX paths and arguments.

NOTE: The argument -rf is passed, by default.

Code Syntax

 - delete:
     file: <file or folder which you want to delete>
     args: <arguments>

Example

Path: ws/path/to/file
Argument: -f

UpdateJSON

Updates the value of the specified key in the specified JSON file, based on the UNIX paths and arguments.

NOTE:

If you need to update multiple keys, you must use multiple updateJSON operations.
If you want to update nested keys, you must provide the keys in the Key1.Key2.Key3... format.

Code Syntax

 - updateJson:
     file: <json-file-path>
     key: <key>
     value: <value>

Example

Path: ws/path/to/file
Argument: -f

Replace

Replaces the specified text in the specified file, based on the UNIX paths and matching regex values.

Code Syntax

 - replaceText:
     file: <filePath>
     regex: <regex-pattern>
     value: <replaced-string>

Example

Path: ws/path/to/file
Argument: -r

Sample YAML File

Following is a YAML file that displays sample configurations for custom build parameters:

version: 1.0
phases:
    PRE_BUILD:
        propagateBuildStatus: true #(can be true or false)
        operations:
            
            [ "IOS_TABLET_NATIVE", "ANDROID_MOBILE_NATIVE", "RESPONSIVE_WEB" ]:
            # Copy file
            - copy:
                src: "PROJECT_WORKSPACE/<example-file>"
                dest: "PROJECT_WORKSPACE/<target_dir>/<example-file>"
            # Copy entire directory
            - copy:
                src: "PROJECT_WORKSPACE/<example-dir>/"
                dest: "PROJECT_WORKSPACE/<target-dir>/<example-dir>"
                args: "-r"
            
            [ "ANDROID_MOBILE_NATIVE" ]:
            # Updating key value in json
            - updateJson:
                file: "PROJECT_WORKSPACE/<example-file>.json"
                key: "<key>"
                value: "<value>"
            # Replacing text with regex
            - replaceText:
                file: "PROJECT_WORKSPACE/<example-file>"
                regex: "<regex>"
                value: "<value>"
            [ "ALL" ]:
            # Delete directory
            - delete:
                file: "PROJECT_WORKSPACE/<example-dir>"
                args: "-rf"
            # Delete files
            - delete:
                file: "PROJECT_WORKSPACE/<example-file>"

    # The POST_BUILD phase includes commands that execute after the Build has completed.
    POST_BUILD:
        operations:

    # The PRE_TEST phase include commands that execute before the Tests are initiated.
    PRE_TEST:
        operations:

    # The POST_TEST phase include commands that execute after the Tests have been executed.
    POST_TEST:
        operations:

Upload Test Data Files

From the 202401 release, App Factory supports the uploading of Test Data files in the Custom Build Configuration page to include Test Data in the build.

Follow these steps to upload a Test Data file in the Custom Build Configuration:

Open the Visualizer folder of your App Factory project, and then select Custom Build Configuration from the left panel.
Under the YAML Configuration section, select the Upload Data Files checkbox.

The Choose File button appears.
Click Choose File.
Locate the file that you want to upload, select it, and then click Upload.
The file name appears next to the Choose File button.
NOTE:
- You can only upload .zip files that contain the Test Data for the project.
- If you want to change the file that you have already uploaded, click the X next to the file name to remove the file, and then upload the required file by using the Choose File option.
Click Save & Exit.
The Test Data file is uploaded to the Custom Build Configuration job, and will be executed when you build the Visualizer project.

Common Environment Variables

The following table lists the environment variables that are common to all platforms in App Factory. These environment variables are exposed during the execution of Custom Builds in the channel jobs.

Parameter	Platform
PROJECT_BUILDNUMBER	All
CHANNEL_BUILDNUMBER	All
CHANNEL_NAME	All
PROJECT_WORKSPACE	All
BUILD_TYPE	All
PROJECT_NAME	All
PROJECT_VMWORKSPACE_PATH	iOS
PROJECT_XCODEPROJECT	iOS
CUSTOM_DATA_PATH	All

Platform Specific Environment Variables

Following are the environment variables for different platforms in App Factory. These environment variables are exposed during the execution of Custom Builds in the channel jobs.

Parameter	Platform
ANDROID_APP_VERSION	Android
ANDROID_KEYSTORE_FILE	Android
ANDROID_KEYSTORE_PASSWORD	Android
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
FORM_FACTOR	Android
GOOGLE_MAPS_KEY_ID	Android
ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES_ENABLEMENT	iOS
CLOUD_CREDENTIALS_ID	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
IOS_DISTRIBUTION_TYPE	iOS
APPLE_WATCH_EXTENSION	iOS
FORM_FACTOR	iOS

For more information on Environment Variable parameters, refer Configuring Parameters for Building a Visualizer App.