Replacements
- 1 Overview
- 2 Getting Started
- 3 YAML Definition
- 4 Execution
- 5 Sample Replacement Configurations
- 5.1 Simple string replacement in all .xml files
- 5.2 Simple string replacement in all files when deploying to a specific Environment
- 5.3 Replace in a specific file when deploying to non-prod environments
- 5.4 Replace string when the Project Target / Instance property matches a value
- 5.5 Replace string in all files with Project Target / Instance property
- 5.6 Find a string using regex and replace it with a string
- 5.7 Find a string using regex and replace it with a return value of the Groovy script
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 |
|---|---|---|---|
[replacmentsRoot] denoted | Array | Multiple replacments can be defined in the yaml configuration and are separated by | Every replacement in the file must start with |
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: Example 3 (multiple conditions) replaceWhenEnv: - env: FDBLD_IS_MAIN_BRANCH |
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.
- style