BuildForge Help

Selectors

Server selectors allow you to describe the kind of server that a project or step should use by listing desired properties and values. When you apply a selector to a project or step, the system uses the selector to determine which servers are valid choices for the task, and then selects an available server from the valid ones.

You can use selectors to be specific (choosing a specific server by name) or general (any Windows® server). A selector is a list of properties which describe the desired server. To manage selectors, use the Servers > Selectors page.

If you want to select servers based on properties you define, create appropriate collector properties first. For example, you can create a collector with a property named BUILDING (with a value equal to the name of the building that houses a server). This allows you to select servers based on their physical location. However, when you create selector variables, you must choose properties from a list that the system generates from all of your collectors.

If a selector does not find a server that matches its property list, then the project or step fails and the system creates a build note.

A selector contains a list of property/value pairs called variables. For each variable, you can specify a value and a comparison. For example, you could specify a property "CompilerVersion = 1.1" to select only servers that have that property, but you could also specify "CompilerVersion >= 1.1" to select servers with versions 1.1, 1.3, 2, and 2.0. Selectors support numeric and string comparison operations.
  • A variable can be required or optional. When multiple servers match the required variables, the system picks the one that matches the most optional variables.
  • You can repeat optional variables in a selector, to increase the score of a server that matches them. For example, you might require MEM_TOTAL> = 1GB but repeat MEM_TOTAL >= 2 GB three times to bias the system to choose servers with memory of at least 2 GB. See below for the details of how the system makes its choice.
  • You can use the .include statement to add environment variables from another selector. The .include statement references an environment. If there are duplicate variables in environments, the system counts each instance of the variables when it assigns scores to servers.
To choose a server, the system:
  1. Compiles a list of the servers which contain all the required variables in the selector.
  2. Rates each server, granting the server a point for each optional variable it matches.
    • If the selector contains more than one copy of the same variable, the extra copies grant extra points to servers that match them.
    • The system assigns one extra point to the server with the lowest BF_LOADRATIO value.
  3. Chooses server that received the most points.

Although it does not appear in a server's manifest, the property BF_NAME is automatically assigned to every server; its value is the logical name of the server. To create a selector for a specific server, create a selector variable that selects BF_NAME=<logical server name>.

When comparing selector variables with manifest properties to look for matches, the system looks at the variable's value and the manifest property's value. The system performs a lexical (string) comparison unless both values match the following criteria for numbers:

  • If the value starts with a digit and contains only digits and decimal points followed by at least one digit, the system performs a numeric comparison.
    • 5, 5.5, 0.5, 5.0, and 5.5.5 are considered numbers.
    • 5., .5, 5.., 5..5, 5.4.6_05, and 5.6i5 are all considered strings
  • A numeric value containing more than one decimal point causes a sub-version numeric comparison, where the system compares each decimal-separated section. While 5.21 is less than 5.3 (ordinary numeric comparison), 5.21.0 is greater than 5.3 (sub-version numeric comparison).
Note: The system always performs a string comparison if you use the "contains"operator. Also, the "contains" operator is case-insensitive.
Table 1. Selector/Manifest Comparison Examples

Property Name

Manifest property value

Operator

Selector Variable Value

Comparison Type

Match?

PerlVersion v5.8.4 >= 5.2.1 Lexical Yes
PerlVersion v5.8.4 >= v.5.2.1 Lexical Yes
PerlVersion v5.8.4 >= v5.22.1 Lexical Yes
OS_VERSION 1.15 >= 1.1 Numeric Yes
OS_VERSION 1.10 >= 1.1.0 Sub-version numeric Yes
BF_NAME WinServer1 contains win Lexical Yes
BF_NAME Server123 = 123 Lexical No