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.

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

---
fileName:  Opportunity.object
replacements: 
  - stringToReplace:  http://www.fedex.com
    replaceWithString: http://www.test.fedex.com
    replaceWhenEnv: [DEV,QA,UAT]

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

---
fileName:  *.object
replacements: 
  - stringToReplace:  https://api.goshippo.com
    replaceWithString: https://test.goshippo.com
    replaceWhenEnv:  
      - env: FDSF_ACCOUNT_CODE
        value: FLEXAGON9

Replace string in all files with Project Target / Instance property

---
replacements: 
  - stringToReplace:  'https://api.goshippo.com'
    replaceWithEnv: GO_SHIPPO_SERVICE_URL

Find a string using regex and replace it with a string

---
replacements: 
  - regexToReplace:   "OWNER = \"[^\"]+\""
    replaceWithString:  'OWNER = "system"'

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.

---
fileName: "*.ldt"
replacements: 
  - regexToReplace:   "LAST_UPDATE_DATE = \"\\d{4}/[01]\\d/[0-3]\\d\\s[0-2]\\d((:[0-5]\\d)?){2}\""
    replaceWithGroovyResults:  new java.text.SimpleDateFormat("'LAST_UPDATE_DATE  = \"'yyyy/MM/dd HH:mm:ss'\"'").format(new Date())
  - regexToReplace:   "LAST_UPDATE_DATE = \"\\d{4}/[01]\\d/[0-3]\\d\""
    replaceWithGroovyResults:  new java.text.SimpleDateFormat("'LAST_UPDATE_DATE  = \"'yyyy/MM/dd'\"'").format(new Date())