Using variables and expressions in FreeMarker templates

XL Deploy uses the FreeMarker templating engine to allow you to access deployment properties such as such as the names or locations of files in the deployment package.

For example, when using rules to customize a deployment plan, you can invoke a FreeMarker template from an os-script or template step. Also, you can use FreeMarker templates with the Java-based Generic plugin, or with a custom plugin that is based on the Generic plugin.

Available variables

The data that is available for you to use in a FreeMarker template depends on when and where the template will be used.

Available expressions

The XL Deploy FreeMarker processor can handle special characters in variable values by sanitizing them for Microsoft Windows and Unix. The processor will automatically detect and sanitize variables for each operating system if the FreeMarker template ends with the correct extension:

  • For Windows: .bat.ftl, .cmd.ftl, .bat, .cmd
  • For Unix: .sh.ftl, .sh

It uses the ${sanitize(password)} expression to do so (where password is an example of a variable name). If the extension is not matched, then the processor will not modify the variable.

When auto-detection based on the file extension is not possible, you can use the following expressions to sanitize variables for each operating system:

  • ${sanitizeForWindows(password)}
  • ${sanitizeForUnix(password)}

Where password is an example of a variable name.

Accessing dictionary values in a FreeMarker template

You can use dictionary entries from within FreeMarker template; for example, if you want to send an email that contains all dictionaries and their values after a successful deployment.

You can access a dictionary and its properties using following access path in your FreeMarker template:

  • deployedApplicationenvironmentdictionariesdictionaryname (String)
  • deployedApplicationenvironmentdictionariesdictionarytype (String)
  • deployedApplicationenvironmentdictionariesdictionaryentries (Map[String, String])

The name and type are straightforward to reference while iterating through a list of dictionaries. The entries property is a map of string values, so you need a FreeMarker directive to print it.

The following example iterates through every dictionary associated with a deployed application and prints its name, type (dictionary or encryptedDictionary), and entries:

<#list deployedApplication.environment.dictionaries as dict>
    Dictionary: ${dict.name} (${dict.type})
    Values:
        <#list dict.entries?keys as key>
            ${key} = ${dict.entries[key]}
        </#list>
</#list>

Note that the deployedApplication object may not be available by default in FreeMarker template, but you can add it using your rule step configuration as in the following example:

<os-script>
    <script>...</script>
    <freemarker-context>
        <deployedApplication expression="true">deployedApplication</deployedApplication>
      </freemarker-context>
</os-script>