Properties and target groups

A target group is a set of users having the same properties or attributes, such as email domain, language, geolocation, device, or software version.

Create an unlimited number of target groups in the CloudBees platform. Each target group configuration can have nested conditions for complex logic and unlimited attributes, allowing you to finely tune a given audience for a feature flag.

Multiple flags can all have the same targeting, and updating a single target group definition applies to all flags that use the target group in their flag configurations.

Set up a target group for internal testing only, for example, and use it across multiple flags to test new features. Once internal testing is complete, modify the target group to roll out the new features to external users.

Create target groups using custom or built-in properties defined in the code. Learn more about defining properties in the SDK references, and using properties and target groups to configure flags.

The following property types are available:

Boolean
Number (some code languages use Double and Int)
String
SemVer (pre-release and patch labels are not supported.)

Custom targeting properties

Add a custom property to your connected app code for use in target groups, then run the app to display the property options in the UI. For example, the following code within a connected JavaScript app results in the target group options displayed below.

Rox.setCustomStringProperty('company', getCompany())
Rox.setCustomBooleanProperty('isBetaUser', betaAccess())
Rox.setCustomBooleanProperty('isLoggedIn', isLoggedIn())▼

Figure 1. Custom properties options are highlighted.

Usage examples: Explicit custom properties

Define explicit custom properties depending on the code language of your connected application:

Rox.setCustomNumberProperty("numberProperty", 100)
Rox.setCustomStringProperty("stringProperty", "something")
Rox.setCustomBooleanProperty("booleanProperty", true)

Rox.setCustomBooleanProperty("isPaying", () => Account.sharedInstance().paying)
Rox.setCustomBooleanProperty("isPayingUser", context => context.user.isPayingUser())

Rox.setCustomStringProperty("email", () => Account.sharedInstance().email())▼

rox.SetCustomStringProperty("serviceName", serviceName)

rox.SetCustomComputedBooleanProperty("isPaying", func(context context.Context) bool {
        value, _ := context.Get("is_paying_user").(bool)
        return value
    })▼

Rox.setCustomStringProperty("serviceName", serviceName);

Rox.setCustomComputedBooleanProperty("isPayingUser", new CustomPropertyGeneratorWithContext() {

  @Override
  public Boolean generateProperty(Context context) {
    return context.user.isPayingUser();
  }
});▼

# simple String property
Rox.set_custom_string_property('SomeKeyName', 'SomeValue')

# simple Boolean computed property
Rox.set_custom_boolean_property('isPaying', lambda context :
        context['is_paying_user']
)▼

Usage examples: Implicit custom properties

A dynamic custom property rule handler is called when an explicit custom property definition does not exist in the platform.

If you do not define this rule handler, the default function is activated, which tries to extract the property value from the context by its name.

A generic implementation of that handler is described by the following:

(propName, context) => context ? context[propName] : undefined▼

Create this handler for implicit custom properties, depending on the code language of your connected application:

const options = { dynamicPropertyRuleHandler: (propName, context) =>
                                 getLoggedInUser().properties[propName] };
Rox.setup(environmentKey, options);▼

options := server.NewRoxOptions(server.RoxOptionsBuilder{
  DynamicPropertyRuleHandler: func(args model.DynamicPropertyRuleHandlerArgs) interface{} {
    if args.Context != nil {
      if account := args.Context.Get("account"); account != nil {
        return account.(map[string]interface{})[args.PropName]
      }
    }
    return nil
  },
})
<-rox.Setup(<ROLLOUT_KEY>, options)▼

RoxOptions options = new RoxOptions.Builder()
  .withDynamicPropertyRule(new DynamicPropertyRule() {
        @Override
        public Object invoke(String propName, Context context) {
            return (context != null) ? ((Map<String, Object>)context.get("account")).get(propName) : null;
        }
    })
  .build();
Rox.setup(<ROLLOUT_KEY>, options);▼

def handler(prop_name, context):
  if prop_name.startswith('account.'):
    account_prop = prop_name.split('.')[0]
    return context['account'].properties[account_prop]
  return None

options = RoxOptions(dynamic_property_rule_handler=handler)
Rox.setup(environment_key, options)▼

Built-in targeting properties

The following table lists built-in targeting, in the format of rox.<attribute name>:

Table 1. Built-in target group attributes
Attribute name	Description	Data type
`rox.app_release`	Application release version.	SemVer
`rox.distinct_id`	Universally unique identifier (UUID).	String
`rox.language`	ISO 639 two-letter language code. For example, "en" for English, "es" for Spanish, and "zh" for Chinese.	String
`rox.now`	Current time.	DateTime
`rox.platform`	Code language or framework name. For example, "Python" or "Gradle".	String
`rox.screen_height`	Screen height in pixels.	Number
`rox.screen_width`	Screen width in pixels.	Number

If you are using a client-side SDK, and the value of a custom property changes while the app is running, such as after a user signs in, you may need to use Rox.unfreeze().

Access a target group

Display configured target groups for an organization/sub-organization.

To access a target group:

Select the next to Feature management on the left pane, and then select Target groups.
(Optional) Search for a specific target group, by entering all or part of a target group name into Search.
(Optional) Select an option in Sort by to sort the target group list by either ASCENDING or DESCENDING alphanumerical sort order.

The target groups are displayed according to your search or sort criteria.

Create a target group

Use custom properties or built-in attributes (ROX PROPERTIES) to define user segments. You can also create targeting dependent on other target groups.

You can only create nested statements based on target group options as long as there are no circular dependencies on other target groups.

Select the next to Feature management on the left pane, and then select Target groups.
Select CREATE TARGET GROUP.
Enter a Name, an optional Description, and select one of the following conditions:
(Optional) Select the Property condition.
1. Select a Property name from the options.
2. Select an Operator from the options (including regular expression matching).
3. Enter a Value, if the property type is not a boolean.
  
  Select your keyboard Enter/Return key after entering each value to add multiple values when the equals one of operator is selected.
(Optional) Select the Target group condition.
1. Select a Matches … logical operator option.
2. Select a Target group from the options.
(Optional) Select ADD CONDITION to add more conditions.
1. Select one of the following logical operator options:
  - Matches all of the following (AND operator)
  - Matches any of the following (OR operator)
    
    All subsequent conditions use the same logical operator.
2. Configure either a Property or a Target group condition.
Select SAVE when all conditions are added.

Your target group is created, and listed in Target groups.

Select the next to a condition to remove it. However, you must have at least one condition.

Figure 2. An example target group created with multiple conditions.

Use regular expressions

Regular expression (regEx) matching is an Operator option in target group creation.

Figure 3. An example of using regEx matching in the target group UI.

The underlying code on the SDK is:

function regexMatch(str, pattern) {
    var regex = new RegExp(pattern, "");
    var match = regex.exec(str);
    return match ? true : false;
}▼

import (
  "regexp"
)
boolean regexMatch(String str, String pattern){
  matched, _ := regexp.MatchString(pattern, str)
  return matched;
}▼

boolean regexMatch(String str, String pattern){
   int options = 0;
   Pattern r = Pattern.compile(pattern, options);
   Matcher m = r.matcher(str);
   return m.find()
}▼

import re

# In the above example
#    str is the email property value
#    pattern is "@cloudbees\.com$"
re.search(pattern, src, 0)▼

The following provides more information:

expect(parser.evaluateExpression('match("111", "222"')).toEqual(false);
expect(parser.evaluateExpression('match("22222", ".*")')).toEqual(true);
expect(parser.evaluateExpression('match("22222", "^2*$")')).toEqual(true);
expect(parser.evaluateExpression('match("[email protected]", ".*(com|ca)")')).toEqual(true);
expect(parser.evaluateExpression('match("[email protected]", ".*car\\.com$")')).toEqual(true);
expect(parser.evaluateExpression('match("US", ".*IL|US")')).toEqual(true);
expect(parser.evaluateExpression('match("US", "IL|US")')).toEqual(true);
expect(parser.evaluateExpression('match("US", "(IL|US)")')).toEqual(true);▼

Delete a target group

Delete any unused target group.

Before you can delete a target group, you must first remove all references to it in all flag configurations.

A deleted target group is completely removed from the CloudBees platform, including all environments, and deletion is irreversible.

To delete a target group:

Select the next to Feature management on the left pane, and then select Target groups.
Select the next to the target group you want to delete.
Select Delete.
Remove all references to the target group in all flag configurations, if you have not already done so.
1. Select the next to each displayed environment.
2. For each flag in each environment, select EDIT CONFIGURATION.
  
  Figure 4. Select EDIT CONFIGURATION to remove the target group reference.
3. Remove the target group reference.
4. Return to the target group you want to delete and select Delete.
Select DELETE.

The selected target group is deleted and removed from the target group list.