Skip to content

Environment Variables

The Custom Hooks feature in Volt MX App Factory allows you to add a custom pipeline at specific points to an existing pipeline by using custom code/programs. Using the Custom Hooks feature, you can extend and customize the build process, while maintaining the core functionality of the App Factory build process. You can write custom logic and use it to override an existing operation or perform a new operation. For more information on Custom Hooks, refer Configuring Custom Hooks.

HCL App Factory 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 Custom Hook.
For example, you can access Android specific environment variables that will be exposed when you run Android specific jobs on Custom Hooks.

Custom Hooks 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.

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 build execution of Custom Hooks in the channel jobs.

Parameter Platform
DEFAULT_LOCALE All
FOUNDRY_APP_CONFIG All
RUN_CUSTOM_HOOKS All
RECIPIENTS_LIST All
PROJECT_BUILDNUMBER All
PROJECT_NAME All
BUILD_MODE All
CLOUD _CREDENTIALS All
PROTECTED_KEYS All
PUBLISH_FOUNDRY_APP All
PROJECT_SOURCE_CODE_BRANCH All
PROJECT_SOURCE_CODE_REPOSITORY_CREDENTIALS_ID All
PROJECT_WORKSPACE All

Platform Specific Environment Variables

Following are the environment variables for different platforms in App Factory. These environment variables are exposed during the build execution of Custom Hooks 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
PROJECT_VMWORKSPACE_PATH iOS
PROJECT_XCODEPROJECT iOS

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

Custom Hook 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 values mentioned for all the parameters and properties change dynamically based on your selection at the run-time.

Predefined Platform Binary Locations for Respective Platforms

For retrieving artifacts in post build Custom Hooks, 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

Sample Use-Case Scenario

For example, if you have installed Volt MX Iris 7.3 on your Mac machine. You follow a few manual steps to build the IPA by extracting the KAR on your Mac machine. During the IPA generation, you perform additional manual settings in the Xcode project to change the deployment target as shown in the following image.

When you modify the Xcode Project's General Settings, these settings will update the projectpbx (VMAppWithVoltMXlib.xcodeproj/project.pbxproj) file in your local Xcode Workspace folder. Since you modified the Deployment Target in the Xcode settings, it internally modifies 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="VMAppWithVoltMXlib.xcodeproj/project.pbxproj"/>

     <property name="lt" value="&#60;"/>
     <property name="gt" value="&#62;"/>

     <echo message="Updating deployment target" />
    <replaceregexp 
        file="${PROJECT_VMWORKSPACE_PATH}/${PROJECT_XCODEPROJECT}" 
        match='IPHONEOS_DEPLOYMENT_TARGET(.+?)/string' 
        replace="IPHONEOS_DEPLOYMENT_TARGET${lt}/key${gt}
                &#10;${lt}string${gt}${IPHONEOS_DEPLOYMENT_TARGET}${lt}/string" 
        flags="gism" 
        byline="false"/>
</target>

If you want to run this program as part of the App Factory build during the IPA generation, you must hook this program through the App Factory Custom Hook Dashboard. But you need the location of the Xcode Project or the project workspace on App Factory.

App Factory exposes all the job build parameters and file-system variables to Custom Hooks. You can directly access these environment variables in the ANT and MAVEN scripts.

Note: The program can be written in any programming language, but, it must be executed by an ANT or MAVEN script that App Factory invokes during the execution of the Custom Hook in the build process.

Adding Custom Hooks in App Factory

  • You can use the PROJECT_VMWORKSPACE_PATH variable in the ANT file to get the absolute path of the Xcode project in the App Factory Workspace.
  • To update the Deployment Target on Xcode, you must update the VMAppWithVoltMXlib.xcodeproj/project.pbxproj file that contains the IPHONEOS_DEPLOYMENT_TARGET key. You can make similar changes in the project for custom requirements using Custom Hooks.
  • Add the following ANT script to the build.xml file of the Custom Hook that contains the logic to update the IPHONEOS_DEPLOYMENT_TARGET key with the required version mentioned in the SCRIPT_ARGUMENTS.
    SCRIPT_ARGUMENTS is passed as the argument during the Custom Hook upload.
<project name="default" default="project_xcodesettings_update">
<target name="project_xcodesettings_update">
     <property name="PROJECT_XCODEPROJECT" value="VMAppWithVoltMXlib.xcodeproj/project.pbxproj"/>

     <property name="lt" value="&#60;"/>
     <property name="gt" value="&#62;"/>

     <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}
                &#10;${lt}string${gt}${IPHONEOS_DEPLOYMENT_TARGET}${lt}/string" 
        flags="gism" 
        byline="false"/>

<echo message="Updated deployment target to ${IPHONEOS_DEPLOYMENT_TARGET}" />
</target>
</project>

```*   Add the **build.xml** file to a zip file, and upload it to the Custom Hook Dashboard 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 Custom Hooks, refer [Configuring Custom Hooks](CustomHooksIris.md#configuring-custom-hooks).

Custom Hook build.xml (Ant Script) 

 <switch value="${FOUNDRY_APP_CONFIG}">
 <case value="DEV_ENV_NAME_ID">
         <property name="environmentvalue" value="DEV"/>
 </case>
 <case value="SIT_ENV_NAME ">
         <property name="environmentvalue" value="SIT"/>
 </case>
 <case value="PROD_ENV_NAME ">
         <property name="environmentvalue" value="PROD"/>
 </case>


 <echo message="Copying environment specific object svc folder"/>
       <copy file="../modules/Objectsvc/${environmentvalue}/objectSvcMeta.js"
                      todir="../modules" overwrite="true"/>
 <echo message="Copied environment specific object svc folder"/>
 <echo message="Editing i18 file based on environment"/>
       <propertyfile file="../i18n.properties">
            <entry key="i18n.getAppURL.value" value="${environmentvalue}~|~"/>
       </propertyfile>
 <echo message="Edited i18 file based on environment"/>


```