About the Environments panel

Use the Environments panel to create and manage environments for your projects. To view the panel, select Environments.

List of environments shown in the Environments panel

In the Environments panel, you can also click an environment to display and edit its variables.

Details tab

Environment properties

Specify the following environment properties:

Name
The name for the environment.
Access
The access group of users who can use this environment.

Variable properties

In the Environments panel, select a variable to view the Variables panel. Use the Variables panel to specify the following properties:

Name
Variable names can use only alphanumeric characters (a-z, A-Z, 0-9) and the underscore character ( _ ) in a name. The maximum length is 255 bytes:
  • Single-byte character sets: 255 characters
  • Double-byte character sets: 127 characters
Value
Variable values have the following characteristics:
  • Length: Values can be any length (up to the operating system limit, if there is one).
  • Special characters: The characters %, $, [, ], {, }, \, ", and ' have special meanings for the pre-parser (before OS evaluation) and for evaluation on the operating system. Avoid using them. Escape them with a backslash (\) to pass them. See Interpretation of variables in steps.

    If a value is in single quotes, variable names are passed as literals rather than interpreted. For example, a variable assignment MyEnv='$env' causes the string $env to be assigned to MyEnv, rather than the value of variable $env.

  • Variables in values: if a variable is in a variable value, that variable is interpreted when a step using the variable is run.
  • Pulldown values: To specify items for a pulldown variable, set the variable type to Pulldown List, save the variable, and then edit it. Click the Pulldown Options tab to add items to the pulldown. See Creating pulldowns for a variable.
  • Dot commands as values: Some dot commands can be used as the value of an environment variable; in these cases, the system replaces the dot command with other values. See Using dot commands in variables.
  • Carriage returns: Variables do not store carriage returns. You can assign a multiple line value to a variable, as shown in the following example. The contents of the file text.txt are assigned to the variable test:
    .bset env "test = `type text.txt`"
    The lines in the file are concatenated. For example, suppose the file's contents were as follows:
    A first line
    And a second line
    The variable's value then becomes the following:
    A first lineAnd a second line
Type
Variables are assigned one of these types:
  • Standard - the default. The variable can have a value and action assigned.
  • Include - the variable value points to another environment to include. All variables in the environment are included.
    Note: The Include variable type replaces the .include functionality provided in prior releases.
  • Pulldown List - the variable contains a set of values that users can choose from. After a pulldown list variable is created, you can select it and click on the Pulldown Options tab to add values.
Action

One of the following:

  • Set: The default option. The specified value is assigned to the variable. The variable is created if it does not exist.
  • Set if not set: This action assigns the value to the variable only if the variable does not already have a value. See About variables.
  • Append: The value is appended to the current value for the variable. The OS-specific PATH delimiter is added between the values:
    • Windows: semicolon (;)
    • UNIX or Linux: colon (:)
  • Prepend: The value is inserted in front of the current value. The OS-specific PATH delimiter is added between the values:
    • Windows: semicolon (;)
    • UNIX or Linux: colon (:)
  • Clear: The value is set to an empty string. If the Value property contains a value, it is not used.
  • Delete / Unset: The variable is deleted from the current applied environment. If the Value property contains a value, it is not used.
  • Assign Hidden: The system assigns the variable, but hides the value in the logs, showing it as "*****". Use this option to hide variable values from users who run the project.
    Important: Use caution if you store sensitive information in hidden variables. It is possible to read the values of hidden variables by inspecting the database or by using an API client. They are not secure for sensitive information, such as passwords.

    Assign Hidden variables are protected from editing by default.  Users that do not have the Edit Hidden Tags permission can not edit these values. However, they can delete and recreate them if they have those permissions.  Users with the Edit Hidden Tags permission can edit these values directly, but must re-enter the value to be used.  This behavior prevents users displaying the value of an Assign Hidden variable by changing its type to Set.

    Note: If a variable in a step is set to Assign Hidden, all variables in that step are treated as if they were set to Assign Hidden.
    Note: Assign Hidden variables only apply to projects. If an Assign Hidden variable is passed to an Adaptor, it no longer remains hidden.

    The system normally changes the syntax of a variable in a command line to the appropriate form for your operating system (%VAR% for Windows®, $VAR for Linux® and UNIX® systems). It does not do this for a hidden variable. The variable is passed directly to the server and the operating system environment of the server interprets the variable.

    Therefore, do not use variable names that could be parsed by either operating system. Examples:
    • $name: if this variable is set to Assign Hidden, then when it is interpreted on a UNIX or Linux system, the operating system attempts to resolve it in its environment, not the Build Forge environment.
    • %address%. if this variable is set to Assign Hidden, then when it is interpreted on a Windows system, the operating system attempts to resolve it in its environment, not the Build Forge environment.
On Project
Defines how a variable is used when you manually start a job. This property affects only variables that are used in environments assigned to a project. The property does not affect variables when the job is running. The value can be one of the following:
  • Normal: The variable behaves normally when assigned to a project.
  • Required: A value must exist for the variable. Variables with this property are highlighted in the Start panel. A value defined in the variable definition is sufficient. If a value is not defined, a job cannot be quick-started or started.

    If a job containing Required variables is started by the scheduler rather than a user, the variables are left unchanged if they currently have a value or blank if they do not have a value.

  • Read-Only: The value cannot be changed.
  • Suppress Display: The variable is not displayed on the Start Job panel. However, the variable exists and can be used in steps.
  • Must Change: The variable value must be changed. Top-level variables with this property are highlighted in the Start panel; if a new value is not entered, the job cannot be quick-started or started.
    Note: If a job that contains Must Change variables is started by the scheduler rather than a user, the variable values are not changed. Also, if a job that contains Must Change variables is started by a class property, the variable values are not changed. Class properties include Start on purge, Start on entry, and Start on exit.

Snapshot tab

An environment snapshot is an instance of an environment. The Snapshot tab provides the name of the snapshot. Use this tab to view or change the snapshot name and comments about the snapshot.


Feedback