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

XL Release allows you to use variables for this kind of information. 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 might want to 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. XL Release supports several types of variable; for example, text, password, number, and list.

Variable scope

In XL 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 (available in XL Release 4.8.0 and later)

How to create a global variable

If you have the Edit Global Variables permission, you can create global variables in Settings > Global variables (available in XL Release 4.8.0 and later). For information about creating, editing, and deleting global variables, refer to 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:

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

Where variables can be used

You can use variables in almost any field in XL Release; for example, in the titles of phases and tasks, in descriptions of phases, tasks, and releases, and in conditions and scripts.

You can create release variables that must be filled in before a release or task can start; refer to Create release variables for more information.

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

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

As of XL Release 7.0.0 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.

    List box variable

  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.

Dynamically populating a List box variable type using a custom script

As of XL Release 8.2.0, 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.

    List box variable_with_value_provider

  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.

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 XL Release’s 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 XL 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, XL 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.

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
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} - available in XL Release 8.5 and later
  • ${release.id}
  • ${release.title}
  • ${release.status}
  • ${release.owner}
  • ${release.description}
  • ${release.flagStatus}
  • ${release.flagComment}
  • ${release.tags}