BuildMaster Documentation

Configuration Variables

Variables allow for extreme flexibility when modeling your deployment plans, and
configuration variables allow you to have the same plan run differently across different servers and environments.

You can define configuration variables at different scopes (release, server, environment, global, etc), and then reference those variables in your plan when using
Operations, If/Else Blocks,
Loop Blocks, etc.
You can also create a runtime variable in a plan itself.

Cascading Variables

Configuration Variables cascade, which means that you can define a variable of the same name in multiple places,
and the correct value will be resolved at runtime. For example, if you define a variable named $HDarsPath
on the Testing environment, when a plan runs against a server in the
Testing environment, that variable will resolve at runtime.

If you also defined $HDarsPath on a single server in the Testing environment, then that
value would be used instead.

This allows for reusing Plans and Templates without having to change local variables. There are times when it
may be appropriate for variables to have different values when they are used different places, and BuildMaster allows for
this.

Resolution Rules

The variable definition that's the "closest" match to the current context is used. This is determined as follows:

Multiple Scopes

You can also assign multiple scopes to a configuration variable; for example, you could define a variable that's associated
with both the Testing environment and the hdars-web role. A multi-scope variable simply
adds precedence to the highest-scope (Promotion is still "closer" than a Environment + Application).

However, this get can get a bit tricky as the resolution rules are simply not intuitive, so we generally discourage this
use. You can create multi-scoped variables from only the Administration section, and they are visible (but not editable)
on servers, server roles, etc., they are associated with.

Variable Types

Configuration variable values may be set to any of the 3 runtime types. Configuration variable values with the following syntax will resolve to the associated type:

list - expression follows the format: @(item1, item2, ...)

map - expression follows the format: %(key1: value1, ...)

string - the default, any values that do not conform to the above 2 formats

A variable value is parsed as if it were an OtterScript string, where the same parsing rules apply, primarily that runtime variables are evaluated.

Because of this, a value can be escaped with the backtick character (i.e. `) if the value is meant to be a literal string but happens to conform to the format of
one of the other types, for example: `@(some attribute) will resolve to a literal string @(some attribute) instead of a list containing a single element
some attribute .

Permissions

Variable permissions are dependent upon the context they are edited and are evaluated eagerly such that if the qualification of an earlier rule is met, the consequence
is validated and processing ends. The rules are as follows:

If a release is in context, then Releases_Manage is required

If a deployable is in context, then Applications_Manage is required for the deployable's associated application (or source application if imported)

If a server or environment is in context, then Infrastructure_Manageis required

If none of the previous qualifications match, then privileges are evaluated against Applications_Manage for the application or application group in context

Sensitive Variables

Configuration variables may be marked "sensitive" which means that their values are only generally visible with manage permissions. This is not to be used for security purposes, only
to replace the value on view-only pages with (hidden). However, anyone that is able to edit a deployment plan could simply call Log-Information $SensitiveVariable; to
view the value.

The secure option for storing passwords, connection strings, or other values intended to be encrypted is
Resource Credentials, as they require special permissions to manage,
and (as per Inedo Extensibility guidelines) should never be written to any logs.

JSON Format & Bulk Editing

Variables at specific scopes can be edited in bulk as a JSON document at any of the scopes as defined in the resolution rules
except for Execution and Promotion. The bulk JSON files are defined as a single root object with property/value pairs in one of two formats, either strings for both name and value, or
a string name and variable object value. String values in both cases follow the variable types
format above and are not JSON arrays/maps.

Variables API

Custom Value Renderers

Variable value renderers are used to control or modify how a specific variable's value is rendered on
an overview page. This can be used to support use-cases such as:

Linking to another page within BuildMaster

Linking to an external tool

Displaying a subset of properties of a map

Adding customized styles or images to a value

Cleanup of names that are too long or unreadable

A value renderer may be specified at the system, application group, or application level, and
applies to variables displayed on the following pages:

Build overview

Release overview

Application settings

Pipeline details

Adding a Custom Renderer

To add a custom renderer, visit the Administration > Variables > Value Renderers tab, and enter the
name and scope of the variable that will use the custom renderer.

Only non-legacy variables are considered when applying a value renderer. Additionally, variables denoted as
sensitive in the UI will be rendered as (hidden) regardless if a value renderer matches or not.

Value Renderer Format

A value renderer is specified as HTML. The rendered HTML also considers variable functions
in context, including for example: $BuildNumber, $Substring(...), and $ApplicationName.
To access the variable's value within the renderer itself, use $Value (or @Value/%Value depending on type).

Because values are rendered as HTML, BuildMaster administrators (i.e. you) are responsible for ensuring
that values are either fully-trusted (i.e. only trusted parties create safe values), or that they are properly
sanitized to prevent Cross Site Scripting attacks, malformed HTML, and more. A number of
helpful functions are included in the InedoCore extension to mitigate these risks such as $HtmlEncode(),
$UrlEncode(), and $JsEncode().