User Variables and Environments

Environments

If the same group of variables are used repeatedly in multiple places, then you may want to use an environment. An environment is a collection of variables, and is configured using the environments top-level section.

Each managed entity or type can reference a single environment. This makes the variables contained within the environment accessible by any samplers defined on that entity or type. When a type is added to a managed entity using an addTypes setting, an environment can also be specified for use by the samplers defined within the type.

It is also possible to nest environments to allow specialisations. Child environments inherit variables from their parent environment.

Define Variables

Variables can be defined in managed entities, managed entity groups, types, environments and operating environment.

A variable definition consists of the variable name and its value. The value can be one of several different types, including strings, integers, a list of items, an active time reference, amongst others.

Where possible, the variable type should fit the intended usage. For example, the sample interval setting takes integer values, so the variable here should be an integer type. Gateway attempts to substitute (for instance) a text value where an integer value is expected, but this does not work for all situations.

To define a new variable using the Gateway Setup Editor (GSE):

1. Navigate to the section you want to make a variable for.
2. Click on the Add new button for the var section.
3. Fill in the variable name and value.

Reference Variables

To use the value of a variable, configure a setting using a variable name instead of a data value.

In the GSE, a setting that supports variables appears with a blue hyperlink stating either data or var.

Click on this text to switch between data and variable modes, and supply the data value or variable name respectively.

Some settings (typically text-valued settings) also support inline usage of variables, which allow the value of a variable to be inserted in the middle of user-supplied text (i.e. a mix of data and var values). To insert a variable reference, click on the var drop-down to the right of the setting and select a variable to use. (See Inline variable storage).

Variable Scoping and Resolution

Variables have scoping rules which define where they are valid and hold values. This means that although the GSE may suggest the name of a variable to use, the variable referenced may not be resolvable in a particular instance.

For example, a sampler which references the variable myVar can be added to managed entities me1 and me2. If me1 defines a value for myVar but me2 does not, then the sampler on me2 will not be able to resolve this reference to a value, and uses an empty value instead.

When a variable reference is used in a sampler or sampler include, it is resolved by looking through the following locations in order until the variable can be found. If it is not found then an empty value is substituted (a gateway validation warning is also produced for this occurrence).

If the sampler or sampler include is referenced by a type:

• The environment specified when the type was added to that managed entity or managed entity group.
• Variables defined directly in the type.
• The environment referenced by the type.

If the sampler or sampler include is referenced in the managed entity or managed entity group, or was not found in the above:

• Variables defined in (or inherited by) the managed entity.
• The environment referenced by the managed entity.
• The operating environment.

For a sampler include, if the variable still cannot be resolved:

• This process is repeated, using the locations that would be searched when resolving variables for the host sampler configuration.

Inherited Variables

Managed entities and environments inherit any variables defined in its ancestor sections in the Gateway setup.

For example, in the screenshot below, managed entity linux1 inherits the three variables shown, as they are defined in the managed entity group linux hosts which contains the linux1 definition.

Inherited variables can also be overridden (a new value given to the variable, replacing the inherited value) by re-defining the variable again with the new value. Additional variables can also be defined as normal.

The screenshot above shows the variables defined in the linux1 managed entity. As this entity is part of the linux hosts group, it inherits the three variables dbhost, dbport, and logdir.

The additional var entries define a new variable dbuser, and override the inherited logdir variable with a new value. This brings the total number of variables for this managed entity to 4 (3 inherited variables with 1 overridden, and 1 new variable).

Configuration