Variables

When creating release templates, you will create tasks that contain information that varies based on the release. For example, you can have one generic release template that is used for the release process of several applications. Different releases based on this template will require different application names.

You can use variables to manage information that:

• Is not known when designing a template, such as the name of the application
• Is used in several places in the release, such as the name of the application, which you can use in task descriptions and email notifications
• May change during the release, such as the version number of the release that is being pushed to production

Variables are identified by the ${ } syntax. Release supports several types of variables. Examples: text, password, number, and list.

Variable scope

In Release, you can create variables with different scopes:

• Release variables can only be used in a specific template or release.
• Global variables can be used in all templates and releases.
• Folder variables can be used in all templates and releases inside a specific folder.

How to create a global variable

If you have the Edit Global Variables permission, you can create global variables in Settings > Global variables. For information about creating, editing, and deleting global variables, see Configure global variables.

How to create a release variable

If you have the Edit Template or Edit Release permission on a template or a release, respectively, you can create a release variable by:

• Typing the variable name in a field in the release flow editor using the ${ } syntax
• Using the Variables screen

For more information about creating, editing, and deleting release variables, see Create release variables.

How to create a folder variable

If you have the Edit folder variables permission on a folder, you can create folder variables in Overview > Folders of the navigation pane, select a folder, then select Variables (available in Release 8.6.0 and later).

For more information about creating, editing, and deleting folder variables, see Configure folder variables.

Skip Nested Variable Interpolation for Text Variable Types

You can skip interpolation of values and prevent Digital.ai Release from creating variables out of it for Text type variables.

Configure this setting by selecting the Variables > Create variable > Prevent variable interpolation check box. This check box is enabled only when you select Text from the Type drop-down list.

Note: It is applicable only for Text type variables. It can be set at Release, Folder, and global levels.

View String Type Variable Values in String Type Fields

Text type fields, by default, fetch and show the values of the String type variables added to them. Text type fields show the variable's name in case the varaible has no values assigned to it.

Here's a Text type field—${title}—for example, with a value assigned to it.

Here's how the Release Title text field shows the value of the String type variable when you add the variable to the Release Title field.

Where variables can be used

You can use variables in most fields in Release releases. Examples: in the titles of phases and tasks, in descriptions of phases, tasks, and releases, and in conditions and scripts.

While global, folder and release variables can be used in input properties of tasks, only release variables can be used in the output properties of such tasks.

You can create release variables that must be filled in before a release or task can start. For more information, see Create release variables.

You can change the values of variables in an active release, although doing so will only affect tasks that are in a planned state.

Examples of using variables inside another variable

In Release version 8.5 and later, you can use variables inside another variable. This does not apply to password types and index/key access of complex types (example, ${list[2]} or ${map['key1']})

Example 1: String variables inside String Type variable

${host} = localhost
${port} = 5516
${url}  = http://${host}:${port}/

Example 2: String variables inside List Type variable

key: 'list',
value: ['${var1}', '${var2}'],

Example 3: String variables inside Set Type variable

 key: 'set',
 value: ['${var1}', '${var2}'],

Example 4: String variables inside Map type variable

key: 'stringMap',
value: {'key1': '${var1}', 'key2': '${var2}'},

Using a List variable as a value in the List box variable types

You can create a List variable and use it as a possible value for a List box variable.

1. Create a global variable or a release variable with the type List.

2. When you create a new variable and select the type List box, click the button next to the Possible values to switch between a list of normal values or a variable of type List.

   

3. Select the second option and choose a List type variable.

4. Click Save.

You can use the List box variable in templates, releases, or tasks allowing users to select the values from predefined List variable.

Using lists of Applications or Environments in the List box variable types

You can choose a list of Applications or Environments to be used as possible values for a List box variable.

Please specify the run-as user and password on the template properties as those credentials will be used to retrieve the available Applications and Environments.

Note: Applications or environments will only be retrieved when the new release is being created and during the User Input task. In all other cases - such as manually changing variable values in either a Template or Release - the list of values will be empty.

Dynamically populating a List box variable type using a custom script

You can use a script to dynamically retrieve possible values inside a List box variable.

1. Create a new List box variable.

2. Select Value provider as the Value provider type.

   

3. Select the Script value provider.

4. Depending on the selected script, you will have different input fields. The script will be evaluated when creating a release.

5. Click Save.

Note: Applications or environments will only be retrieved when the new release is being created and during the User Input task. In all other cases - such as manually changing variable values in either a Template or Release - the list of values will be empty.

Creating a custom script value provider

Creating a new script value provider is similar to the Plugin tasks. For a more detailed explanation of how to extend the Release type system, see Defining a custom task.

Example script value provider

In the synthetic.xml file, you must extend xlrelease.JythonProvider or xlrelease.GroovyProvider:

<synthetic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://www.xebialabs.com/deployit/synthetic"
       xsi:schemaLocation="http://www.xebialabs.com/deployit/synthetic synthetic.xsd">

  <type type="test.Test2ValueProvider" extends="xlrelease.JythonProvider" label="Sample value provider with CI ref"
            description="This value provider has CI ref parameter that points to JIRA server.">
      <property name="jiraServer" label="JIRA server" referenced-type="jira.Server" kind="ci" description="JIRA server to use" />
      <property name="username"  required="false" description="Overrides the username used to connect to the server"/>
      <property name="password" password="true" required="false" description="Overrides the password used to connect to the server"/>
  </type>

</synthetic>

You can store value provider scripts in the ext or plugins directory of the Release server.

• Use ext when you are developing a custom value provider. The ext directory contains custom type definitions in the synthetic.xml file. Scripts are placed in the subdirectories of ext.
• The plugins directory contains bundled plugins that are packaged in a single zip file with the .jar extension.

For the value provider defined above, Release will try to find and execute the python script at this location: test/Test2ValueProvider.py. Value provider scripts must return a list of objects in the variable named result.

note

The properties of the value provider will be injected into the script as well as a dictionary. As a result, you do not need to access the properties as valueProvider.jiraServer but use jiraServer, instead.

The following script can be used to display the title of the JIRA server passed as a parameter to the value provider defined above:

# let's connect to the provided jiraServer
from xlrelease.HttpRequest import HttpRequest
# example of request to the Jira server
req = HttpRequest(jiraServer)
# ...
result = [jiraServer["title"]]
# or
# result = [valueProvider.jiraServer.title]

You can add the following properties to the <type> element to further customize your value provider:

• scriptLocation: Specifies a custom script location that overrides the default rules.

This is an example of a value provider that generates a range of numbers:

<synthetic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://www.xebialabs.com/deployit/synthetic"
       xsi:schemaLocation="http://www.xebialabs.com/deployit/synthetic synthetic.xsd">

    <type type="test.TestValueProvider" extends="xlrelease.JythonProvider" label="Sample script value provider"
          description="This value provider has two parameters for range.">
        <property name="param1" label="Lower bound" default="1" description="Minimum value." required="false" />
        <property name="param2" label="Upper bound" default="5" description="Maximum value." required="false" />
    </type>

</synthetic>

Place the corresponding script into test/TestValueProvider.py:

def generateRange():
    t = range(long(valueProvider.param1), long(valueProvider.param2))
    return t

result = generateRange()

Special release variables

You can use the following special release variables to access the properties of a release:

• ${release.url}
• ${release.id}
• ${release.title}
• ${release.status}
• ${release.owner}
• ${release.description}
• ${release.flagStatus}
• ${release.flagComment}
• ${release.tags}

External Password Variables

Starting with release 9.7, password variables values can be stored in third party secret management systems. These include:

• HashiCorp Vault
• CyberArk Conjur

Included in the 9.7 release are adapters that allow Digital.ai Release to retrieve data from these secret managers. Secrets managed in this way can be used in password fields. Also, starting in 9.7, passwords can also be used in regular text fields if "Allow passwords in all fields" is checked on the release properties tab.

Configuring Secret Server

See the related how-to pages for your server:

• HashiCorp Vault
• CyberArk Conjur

Mapping an external secret.

Any global, folder or release variable can be mapped to an external secret by following these steps:

1. Create a new variable.
2. Choose a Password from the Type drop down.
3. Click on the keyboard icon next to the default value text field.
4. Choose your preconfigured Vault or Conjur server.
5. For Vault, you will need to add the path to the secret and the key of the secret.
6. For Conjur, you will need to add the path to the secret only.

Once this is saved, the variable can be used like any other password variable.

Restrictions on external password variables.

• External secrets can only be mapped to password variables.
• External secrets are treated as string values.
• External secrets cannot be used in dictionary values.
• The value from an external secret are not passed to scripts via the globalVariable, folderVariable or releaseVariable dictionary within a script.
• The value from an external secret can not be retrieved from Release REST API.
• The path specified in creating the external secret is not validated. It will be resolved during the release execution.