Replacements

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

Regix 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.

 

The following macros are not currently supported in the footer:
  • style