Share global variables with configuration objects

In XL Release you can define configuration objects to store settings that will be used across many tasks, task types, or information that must be accessible in tasks but which the user configuring the task may not know. Common examples include connection information for Jenkins or JIRA servers, or remote hosts on which to execute scripts.

You can also define your own configuration types to share information between custom tasks or to make information available to out-of-the-box task types that you want to extend.

In the example scenario that follows you will use a configuration object to store a number of global variables and reference them within a custom task type.

Defining the configuration type

To define your configuration type, there are two base types that you can use: xlrelease.Configuration and configuration.HttpConnection. The latter is useful if you want to define any kind of HTTP endpoint, but in this case you can use something basic:

<type type="my.GlobalConfig" extends="xlrelease.Configuration">
    <property name="foo" label="Foo (this does X)" />
    <property name="bar" required="false" label="Bar (this does Y)" />
</type>

This defines a very simple configuration type with two properties, “foo” and “bar”. Properties can be required or optional and can be marked as “password” properties if desired.

Creating a configuration object

After you defined your configuration type, create a configuration object of that type.

  1. Go to Settings > Shared configuration.

  2. Under My: Global config, click Add Global config.

You can create multiple configuration objects. To define global variables, a single instance is required.

Linking the configuration type to custom task types

To access the configuration object from a custom task, add a reference to the definition of your custom task type:

<type type="my.SampleTask" extends="xlrelease.PythonScript">
    <property name="globalVars" kind="ci" referenced-type="my.GlobalConfig" required="false" category="input" />
</type>

The user creating an instance of a custom task can select a configuration object for that task. Specify category="input" for the property, to expose it to the task implementation.

Using the configuration object from the task implementation

The property is exposed to the task implementation as a Jython variable of the same name as the property. Configuration objects are accessible as Jython maps. Example that prints the global values:

import sys

print "DEBUG: global", globalVars, "\n"
print "DEBUG: global 'foo'", globalVars['foo'], "\n"
print "DEBUG: global 'bar'", globalVars['bar'], "\n"

sys.exit(1)

The script is saved as XL_RELEASE_SERVER_HOME/ext/my/SampleTask.py, using the standard XL Release naming convention for task implementations. Note The script in this example is designed to fail for easier development and debugging.

Creating a custom task and linking it to a configuration object

When a user creates a task of your custom task type in the GUI, they can link the task to a configuration object. If there is only one of these, it is automatically set as the default:

New custom task

Running the custom task

Executing the custom task as part of a release returns the expected result:

Task output

Linking the configuration to standard task types

You can also add a reference to a configuration object to existing task types that extend from xlrelease.PythonScript, such as webhooks or the JIRA or Jenkins tasks:

<type-modification type="jira.CreateIssue">
    <property name="globalVars" kind="ci" referenced-type="my.GlobalConfig" category="input" />
</type-modification>

Users can select a configuration object for those tasks as well, just as for the custom tasks above:

JIRA task with global variables

For the task to use the configuration object, you must override the default script. You can identify which task types extend from xlrelease.PythonScript by checking out their type definitions in the appropriate synthetic.xml type definition file.