Overview

Project Replacements offers a simple configuration to adjust and substitute strings in artifact files with environment-specific values prior to deployment. Configured replacements will be executed on all the artifacts as a pre-step before the deployment execution. The original artifact will not be modified, only the runtime artifact that is getting deployed will have replacements executed. Replacements will be executed on all the artifact files including the files in the archive files (zip, jar, war, and ear). All the binary files will be ignored during the replacements (There will not be any replacements executed on binary files).

The following replacements can be achieved with the configurations:

Replace in all files or restrict to files using wild card or regex.
Replaces archive file files and archive files within archive files recursively.
Find a matching string using simple or regex to replace.
Can configure multiple replacements per file match
Replace only when the Environment variable value matches
Replace with Environment variables (Project / Target / Instance properties)
Replace with content from a file.
Replace with results of a groovy script code.
Replace with one of the comma-separated values randomly.

The Replacements defined in YAML, are found in the project configuration. Each project can have one or more replacement configurations. Each YAML file can have multiple replacements separated by --- in a file.

Getting Started

Open the Project you would like to add replacement configurations, navigate to Configurations → Replacements, and click Get Started.

A guide to getting started will be shown, similar to the following:

# To get started type 'replacement-' and select the template you want to use.
# YAML uses backslash as its escape character and eats the first layer of quote marks.
# Use Double Quotes around values containing '$', '*', or '{'.

# To reference a FlexDeploy property, use the property name directly. No need to prefix with $. Example FD_ENVIRONMENT_CODE.

# Sample replacement
# ---
# fileName: "*.txt"
# replacements:
#  - stringToReplace: "my static string"
#    replaceWithString: "my replaced string"
#    replaceWhenEnv:
#      - env: "FD_ENVIRONMENT_CODE"
#        value: "DEV"
---

Armed with this information, type replacements- and select a replacement configuration you want to use.

Once selected, a sample YAML configuration will be inserted that you can modify as you see fit. See the YAML definition below for more details.

Below is the generated YAML for the simple replacement of a string with another string. In this specific instance, before deploying to any environment, it substitutes the occurrence of the string "COPYRIGHT" with "© 2023 My Company. All rights reserved." across all files.

YAML Definition

While creating/modifying the replacement configuration in the editor, available fields and values will always be suggested to you. As such understanding the YAML definition below is certainly NOT REQUIRED but certainly can be helpful in understanding how things work.

Field	Data type	Description	Notes

Field	Data type	Description	Notes
[replacmentsRoot] denoted `---`	Array	Multiple replacments can be defined in the yaml configuration and are separated by `---`	Every replacement in the file must start with `---` specified on its own line
filename	String	File name to replace string(s). Wildcard characters are allowed. If not specified, it means * (all files).	Optional.
regexFileName	String	Regex to match the files to replace the string.	Cannot have both filename and regexFileName in the same replacement.
stringToReplace	String	The string to be replaced.
regexToReplace	String	Regex that specifies a string pattern to be replaced. eg: <apiVersion>\d+\.0</apiVersion>	Cannot have both stringToReplace and regexToReplace in the same replacement.
replaceWithString	String	Specify the value for the replacement.
replaceWithEnv	String	Specify the name of the Environment variable. The value of the specified will be used for the replacement. You can use the Project, Target, and Instance Properties of FlexDeploy.	Example 1: replaceWithEnv: FD_ENVIRONMENT_CODE Example 2: replaceWithEnv: FD_PROJECT_NAME
replaceWithFile	String	Specify the file with path. All the contents of the file will be used for replacement. eg: /u01/content/copyright.txt , $FD_ARTIFACTS_DIR/fdreplacements/copyright.txt, fdreplacment/copyright.txt (in temp)
replaceWithRandomCSV	String	Specify the comma-separated values. Will be used of them randomly for replacement. eg: Car,Bus,Train
replaceWithRandomCSVFile	String	Specify the path for csv file with column name. Will be used of them randomly for replacement. eg: /u01/content/states.csv , /u01/content/address.csv!state
replaceWithGroovyResults	String	Provide the groovy script. String value will be replaced with returned String.
replaceWhenEnv	String	Replaces when the environment variable matches the value. Can have multiple entries for replaceWhenEnv. The default condition is ‘and’, when multiple exists. FD_ENVIRONMENT_CODE is a default environment variable.	Example 1 (Replacing only when deploying to one or more environments): replaceWhenEnv: [DEV,QA] Example 2 (Replacing when an environment variable matches): replaceWhenEnv: - env: FDBLD_IS_MAIN_BRANCH value: Y Example 3 (multiple conditions) replaceWhenEnv: - env: FDSF_ACCOUNT_CODE value: FLEXAGON8 - env: FDBLD_IS_MAIN_BRANCH value: Y

Execution

The specified replacements will be implemented on all artifacts as an initial step before the deployment workflow commences. You will notice the step Artifacts Initialization: Execute Project Replacements under the execution steps if replacements are configured on the project. To review the number of matches found and replaced in each corresponding file, as well as the position of the file, click on "Logs."

Sample Replacement Configurations

Simple string replacement in all .xml files

---
fileName: '*.xml'
replacements: 
  - stringToReplace:  '<CreatedBy>Taylor Swift</CreatedBy>'
    replaceWithString: '<CreatedBy>System</CreatedBy>'

Simple string replacement in all files when deploying to a specific Environment

---
fileName: '*.xml'
replacements: 
  - stringToReplace:  '<CreatedBy>Taylor Swift</CreatedBy>'
    replaceWithString: '<CreatedBy>System</CreatedBy>'
    replaceWhenEnv: [DEV]

Replace in a specific file when deploying to non-prod environments

Replace string when the Project Target / Instance property matches a value

Replace string in all files with Project Target / Instance property

Find a string using regex and replace it with a string

Find a string using regex and replace it with a return value of the Groovy script

This one is specific to AOL Objects(.ldt files) but can be used for other scenario’s as well.