Using Placeholders in Deployments

Placeholders are configurable entries in your application that will be set to an actual value at deployment time. This allows the deployment package to be environment-independent and reusable. At deployment time, you can provide values for placeholders manually or they can be resolved from dictionaries that are assigned to the target environment.

When you update an application, Deploy will resolve the values for placeholders again from the dictionary. For more information, see Resolving properties during application updates.

important

Placeholders are designed to be used for small pieces of data, such as a user name or file path. The maximum string length allowed for placeholder values is 255 characters.

This topic describes placeholders using for deployments. For information about placeholders that can be used with the Deploy provisioning feature, see Using placeholders with provisioning.

Placeholder format

Deploy recognizes placeholders using the following format:

{{ PLACEHOLDER_KEY }}

File placeholders

File placeholders are used in artifacts in a deployment package. Deploy scans packages that it imports for files and searches them files for file placeholders. It determines which files need to be scanned based on their extension. The following items are scanned:

• File-type CIs
• Folder-type CIs
• Archive-type CIs

Before a deployment can be performed, a value must be specified for all file placeholders in the deployment.

important

In Deploy, placeholders are scanned only when the CI is created. If a file which is pointed to an external file is going to be modified, it will not to be rescanned for new placeholders.

Archives with custom extensions

If you want Deploy to scan archive files with custom extensions as placeholders (such as AAR files which are used as JAR files), you must add a new XL_DEPLOY_SERVER_HOME/centralConfiguration/deploy-artifact-resolver.yaml file with following settings:

deploy:
  artifact:
    placeholders:
      archive-extensions:
        aop: jar
        ear: jar
        har: jar
        jar: jar
        rar: jar
        sar: jar
        tar: tar
        tar.bz2: tar.bz2
        tar.gz: tar.gz
        war: jar
        zip: zip

Special file placeholder values

There are two special placeholder values for file placeholders:

• <empty> replaces the placeholder key with an empty string
• <ignore> ignores the placeholder key, leaving it as-is

The angle brackets (< and >) are required for these special values.

note

A file placeholder that contains other placeholders does not support the special <empty> value.

Using different file placeholder delimiters

If you want to use delimiters other than {{ and }} in artifacts of a specific configuration item (CI) type, modify the CI type and change the hidden property delimiters. This property is a five-character string that consists of two different characters identifying the leading delimiter, a space, and two different characters identifying the closing delimiter; for example, %# #%.

How does placeholder scanning and replacement work

From Deploy v.9.0 onwards, the placeholder scanning and replacement implementation switched from a filesystem-based approach to a streaming approach. This uses the Apache Commons Compress library. The general algorithm is:

• Get an input stream for the deployable
• Depending on the deployable type, process it directly (for file.File artifacts and its derivatives), or convert it to a stream of archive entries (for file.Folder or file.Archive artifacts)
• Scan or replace placeholders in entries that have to be scanned or modified - specifically text files which are not marked to be ignored
• In the case of placeholder replacements, write the file to disk

Archives in archives are also supported. In this case, an internal archive is scanned separately and is written to a temporary file, and only then is written to a target archive entry. The temporary file is deleted after it is written to the root archive.

The new implementation is also much stricter than the previous method. This could result in errors to files that were formerly correctly scanned, causing deployments to fail. Frequently, errors of this sort are due to the archive structure. For more assistance with placeholder issues, see Debugging placeholder scanning. Note that if the archive cannot determine the text file encoding, it will fall back to a JVM character set, usually UTF-8.

If you do not need to check the placeholders for integrity and want to speed up the time to import files, you can also disable placeholder scanning altogether.

Enabling placeholder scanning for additional file types

The list of file extensions that Deploy recognizes is based on the artifact's configuration item (CI) type. This list is defined by the CI type's textFileNamesRegex property in the <XLD_SERVER_HOME>/centralConfiguration/type-default.properties file.

If you want Deploy to scan files with extensions that are not in the list, you can change the textFileNamesRegex property for the files' CI type.

For example, this is the regular expression that Deploy uses to identify file.File artifacts that should be scanned for placeholders:

#file.File.textFileNamesRegex=.+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)

To change this, remove the number sign (#) at the start of the line and modify the regular expression as needed. For example, to add the test file extension:

file.File.textFileNamesRegex=.+\.(cfg | conf | config | ini | properties | props | test | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)

After changing <XLD_SERVER_HOME>/centralConfiguration/type-default.properties, you must restart Deploy for the changes to take effect.

tip

For information about disabling scanning of artifacts, see Disable placeholder scanning in Deploy.

Rescan the Placeholder

Placeholders are only scanned while importing a package into Deploy and if DAR does not specify the scanned placeholders as true.

If the scanPlaceholders does not work, when the file is deployed or just saved as CI (not deployed yet) with scanPlaceholders off, Rescan Placeholder for the deployed or saved file.

To Rescan Placeholder of deployed or just saved file, select the respective file and do the following steps:

1. Click on three dots
2. Select the Rescan Placeholder.

Placeholder scanning using the Jenkins plugin

When you import of a package, Deploy applies placeholder scanning and checksum calculation to all of the artifacts in the package. The CI tools can pre-process the artifacts in the deployment archive and perform the placeholder scanning and the checksum calculation. With this change, the Deploy server is no longer required to perform these actions on the deployment archive.

Scanning for all placeholders in artifacts is provisioned to be performed by the Deploy Jenkins plugin at the time of packaging the DAR file. An artifact in a deployable must have the scanPlaceholders property set as true to be scanned.

For example, when the Deploy Jenkins plugin creates the artifacts, it sets the scanPlaceholders to true for the artifact before packaging the DAR. (Which means artifacts to be scanned for placeholders while importing).

After a successful scanning, the deployment manifest contains the scanned placeholders for the corresponding artifact and sets the preScannedPlaceholders property to false. (Which means the artifacts is already scanned for the placeholder).

When the package is imported in Deploy, the placeholders are scanned.

If you do not want to use the Deploy Jenkins plugin to scan placeholders and you want to scan the packages while importing, you can modify the deployment manifest and change the preScannedPlaceholders to false with scanPlaceholders set as true.

scanPlaceholders: Scan artifacts for placeholders during the execution of a deployment.

preScannedPlaceholders: Allowing one to preset the placeholder values in the manifest.xml file, to lower processing time in deployment. This alleviates scanning the entire package for placeholders, and also allows one to select only those placeholders they want to replace and not all.

Below given is the current behavior of scanPlaceholders and preScannedPlaceholders when the properties are set to true/false

<scanPlaceholders>false</scanPlaceholders>
<preScannedPlaceholders>true</preScannedPlaceholders>
...Placeholders NOT replaced...

<scanPlaceholders>false</scanPlaceholders>
<preScannedPlaceholders>false</preScannedPlaceholders>
...Placeholders NOT replaced...

<scanPlaceholders>true</scanPlaceholders>
<preScannedPlaceholders>true</preScannedPlaceholders>
...Placeholders ARE replaced...

<scanPlaceholders>true</scanPlaceholders>
<preScannedPlaceholders>false</preScannedPlaceholders>
...Placeholders ARE replaced...

Property placeholders

Property placeholders are used in CI properties by specifying them in the package's manifest. In contrast to file placeholders, property placeholders do not necessarily need to get a value from a dictionary. If the placeholder cannot be resolved from a dictionary, it will be handled in the following ways:

• If the property kind is set_of_ci, set_of_string, map_string_string, list_of_ci, or list_of_string, the placeholder is left as-is.
• If the property is of any other kind (for example, string), the placeholder is replaced with an empty string. Note that if the property is required, this will cause an error and Deploy will require you to provide a value at deployment time.

Property placeholders for a specific project

To selectively replace configuration values ​​in JavaScript files see Property placeholder

Debugging placeholder scanning

To debug placeholder scanning, edit the XL_DEPLOY_SERVER_HOME/conf/logback.xml file and add the following line:

<logger name="com.xebialabs.xldeploy.packager" level="debug" />

While working on applications with the placeholders in Deploy, you will be seeing debug statements in the deployit.log file as follows:

...
DEBUG c.x.d.engine.replacer.Placeholders - Determined New deploymentprofile.deployment to be a binary file
...

The zipinfo tool can also be useful when working with archive structures.

Zip archive processing limitations