Properties

Properties are used throughout pulse™ as a way to specify name-value pairs. The value can then be referenced in various contexts by using one of the following two special syntactic forms:

${<property name>}

$(<property name>)

By abstracting a value with a property, the value can be substituted with different values depending on when and where the property is referenced.

Types of Properties

The most frequently used properties in pulse™ are the properties available within pulse files. As all projects are implemented by generating pulse files, these properties are also available for all configuration that falls under your recipes. This type of property can be defined in various ways, see below for details.

Additionally, various areas of configuration within pulse™ also have their own special properties, tailored to a specific purpose. For example, when configuring build hooks, various build-specific properties are made available to the task configuration. These special properties are referenced using the same syntax, and are documented within the pulse™ web interface. As these properties are specific to the context where they are used, but may include some or all of the properties listed below.

Defining Properties

Properties available to pulse files can be defined in various ways:

• By using the <property> element directly in the pulse file. For more details, refer to the reference documentation built into your pulse™ server.
• By defining them on a resource, and importing that resource for the build. Properties introduced in this way are usually used to abstract the location of a build prerequisite (e.g. to allow the prerequisite to be installed in different locations on different agents.)
• By defining them as build properties on a project or build stage. Such properties can be used to parameterise the project configuration for different builds (e.g. to build different targets), and can also be used to manually specify properties for special types of builds.

Although the mechanisms differ, the resulting properties behave in the same way when referenced in the pulse file.

Referencing Properties

Properties may be referenced within pulse files using the syntax described above: ${<property name>} or $(<property name>). This syntax may be used both within attribute values, and within text content between tags. Properties may also be referenced within project configuration that is used to generate a pulse file. In particular, when configuring the details of recipes, including commands and artifacts, you can reference properties. A typical use for this would be to parameterise the targets executed as part of a build. Instead of fixing the target in the project configuration, use a reference to a variable, e.g. $(target). Then, specify the different targets for different build stages using properties.

To see how your property references appear within a pulse file, you can view the pulse file generated for a build as part of the build result. This may aid in using properties during configuration.

Reserved Characters

When using the ${<name>} syntax, only the } character is reserved, and may not be used in the property name.

When using the $(<name>) syntax, the following characters are reserved and cannot be used in the property name:

) ! # % & : ; | / ?

Filters

(Since 2.1.8.) The pipe (|) character can be used to apply a named filter to the reference value. For example:

$(my.property|upper)

will resolve to the value of my.property with all letters converted to upper case. Multiple filters may be specified:

$(my.property|trim|upper)

in which case they are applied from left to right. Filters do not apply to default values, which must be specified after all filters.

Available Filters

Default Values

The question mark (?) character can be used to specify a default value for the reference if it is not defined at the point where it is referenced. For example:

$(my.property?default)

will resolve to "default" if my.property is not defined.

Property Precedence

Properties are added to the build context in a controlled order, so that later properties may override earlier ones of the same name. The precedence of properties is influenced by the level at which the they are configured. The more specific the configuration, the later those properties are introduced (e.g. properties configured non a build stage may override those defined at the project level). Where the relative specificity is unclear (i.e. between project and agent configured properties) a choice was made to introduce agent properties (from resources) first. Based on this, user-defined properties are introduced into the context in the following order:

1. Automatic environment properties (env.*).
2. Project resource properties (based on project-level resource requirements).
3. Stage resource properties (based on stage-level resource requirements).
4. Project properties.
5. Trigger properties, including those passed with a remote API trigger request, or via the web UI trigger prompt.
6. Build stage properties.

Environment Variables

All properties are also available as environment variables in build processes. Pulse automatically converts the property names as follows:

• The name is converted to upper case.
• All periods (.) are replaced with underscores (_).
• PULSE_ is prepended.

For example, a property named "my.property" would become "PULSE_MY_PROPERTY" in the environment.

Note that you can also introduce environment variables into the build using properties that are marked as "add to environment". In this case the property is added to the environment as-is (without converting the name) in addition to the normal PULSE_ version of the property.

Built-in Properties

Various properties are automatically made available by pulse™ to builds. Note that these are also introduced as variables into the environment of child processes, by converting the names as shown.